popagent

Latest change 98a9a832366ede73ff5e61d826d68af4f775db92 - Add safe autonomous deployment and complete project guidance by AkurAI Build

# Native channels

## Architecture

Popagent owns a shared channel implementation; it does not run IRC or treat a
Mastra Web adapter as a room. PostgreSQL is the durable source for channel
configuration, rooms, user messages, and task correlation. This release supports
only the seeded `general` room, displayed as `#general`; room CRUD is deliberately
deferred.

A channel post always names an existing repository workspace. Depending on the
persisted dispatch mode, every message or only `@popagent`/`@orchestrator`
mentions create a queued `popagent_agent_tasks` row in the same transaction as
the message. The existing task runtime and Mastra supervisor perform the work;
channels do not duplicate agent execution. Specialists remain internal to that
supervisor. Task status, progress, final output, and errors are projected into
channel history by joining the correlated task.

`ChannelEventBus` is the process-local real-time fan-out boundary. Posting,
settings changes, cancellation, and task lifecycle transitions publish typed
channel events. Authenticated SSE clients subscribe at
`GET /api/channels/:id/events`, then refresh durable history when notified.
History remains authoritative after reconnect or process restart. Clients use
bounded polling when streaming is disabled and while active task progress is
changing. The SSE stream sends lightweight refresh notifications and 15-second
heartbeats; clients reconnect and resume from durable cursor-based history rather
than treating process-local events as a message store.

## API

- `GET /api/channels` lists configured rooms.
- `GET /api/channels/:id/messages?limit=&before=` returns chronological bounded
  history with a stable message cursor.
- `POST /api/channels/:id/messages` stores a user message and optionally creates
  and enqueues its durable task.
- `GET /api/channels/:id/events` streams typed message, task, and settings events.
- `POST /api/channels/:id/tasks/:taskId/cancel` cancels only a task correlated
  with that channel.
- `GET/PATCH /api/settings/channels` reads and updates enablement, room name,
  dispatch mode, context depth, streaming preference, and activity display.

Bodies, names, context depth, cursors, and history pages are bounded by route and
store schemas. Browser callers always use the fixed local author identity; future
adapters must supply identity only from authenticated adapter configuration, never
from an untrusted message body.

The versioned `channel-settings.sql` migration seeds configuration and
`#general` exactly once. A deleted singleton or room is not recreated after its
migration marker exists. Channel messages have no automatic retention or silent
cleanup. Workspace deletion is blocked while channel history references it;
transcript/task correlation must not disappear as a side effect of repository
removal.

## UI

`/channels/general` is a reloadable shared workspace with history pagination,
repository selection, composer, connection state, task activity, cancellation,
outputs, errors, empty/disabled/failure states, and accessible live status.
Channels are available from primary navigation. `/settings/channels` owns all
persisted channel controls. Desktop uses the normal workspace layout; mobile
uses the existing navigation drawer and safe-area composer treatment.

## Adapter boundary

Future Slack, Discord, or other Mastra Chat SDK adapters map an external
installation/channel/thread tuple to a Popagent channel ID and map the external
sender to `authorId`/`authorName`. Incoming text enters the same bounded post
contract with an explicitly mapped repository workspace. Task output is read
from the same correlated channel message and sent back to the external thread.
Adapters may translate external event delivery, but cannot bypass API auth,
workspace containment, persistence, dispatch policy, task cancellation, or the
supervisor runtime. Slack, Discord, and other adapters remain explicitly deferred
until a concrete installation exists.

## Contract ownership

- `src/channels.test.ts` — settings, atomic dispatch, pagination, bounds, and workspace-history references.
- `src/channels-api.test.ts` — route validation, dispatch policy, history, and cancellation.
- `src/channel-events.test.ts` — typed fan-out, SSE framing, heartbeat, and disconnect cleanup.
- `src/ui/channel-stream.test.ts` — client parsing, abort, reconnect, and polling fallback helpers.
- `src/ui/routes.test.ts` — durable channel and settings URLs.

Channel UI changes require desktop and mobile browser verification, including
connection, event delivery, cancellation, route-away cleanup, reconnect, and
polling fallback under `AGENTS_RULES.md`.