crewly 1.6.5 → 1.7.0

package/dist/backend/backend/src/services/chat-v2/chat-v2.service.js

@@ -10,9 +10,27 @@
  * @module services/chat-v2/chat-v2.service
  */
 import { ChannelStore } from './sqlite/channel.store.js';
+import { EventEmitter } from 'events';
 import { MessageStore } from './sqlite/message.store.js';
 import { openChatDatabase } from './sqlite/chat-db.js';
-import { CHAT_CHANNEL_TYPES, CHAT_CONTENT_TYPES, CHAT_ERROR_CODES, ChatError, } from './types.js';
+import { CHAT_CHANNEL_TYPES, CHAT_CONTENT_TYPES, CHAT_ERROR_CODES, CHAT_SENDER_TYPES, ChatError, } from './types.js';
+/**
+ * Allowed values for `RecordTurnInput.metadata.source` — the audit-trail
+ * discriminator that identifies which subsystem produced the message.
+ *
+ * Per spec `2026-05-14-unified-chat-message-store.md`, every {@link
+ * ChatV2Service.recordTurn} caller MUST set `metadata.source` to one of
+ * these values. The set is intentionally closed so future audits can
+ * `GROUP BY metadata->>'$.source'` without surprise values.
+ */
+export const RECORD_TURN_SOURCES = [
+    'web',
+    'slack',
+    'pty-runtime',
+    'in-process-runtime',
+    'reply-tool',
+    'system',
+];
 // ---------------------------------------------------------------------------
 // Service
 // ---------------------------------------------------------------------------
@@ -30,7 +48,7 @@ const DEFAULT_PRESENCE = () => ({
  * - Maps rows → DTOs.
  * - Fans out to WebSocket / adapters in later phases.
  */
-export class ChatV2Service {
+export class ChatV2Service extends EventEmitter {
     /** Phase A spec §3.2: max mention count per message. */
     static MAX_MENTIONS_PER_MESSAGE = 50;
     /** Phase A spec §3.2: max JSON-encoded byte size of the mentions array. */
@@ -43,6 +61,7 @@ export class ChatV2Service {
     validateTeamMembership;
     now;
     constructor(options) {
+        super();
         this.config = options.config;
         this.db = options.db ?? openChatDatabase({ dbPath: options.config.storage.dbPath });
         this.channels = new ChannelStore(this.db);
@@ -75,6 +94,63 @@ export class ChatV2Service {
     countAllMessages() {
         return this.messages.countAll();
     }
+    /**
+     * Phase 6.0 of unified-chat-message-store spec — replacement for the
+     * legacy `ChatService.updateMessageMetadata`. Merges a partial
+     * metadata object into the stored row's `metadata` JSON column using
+     * SQLite's `json_patch` (atomic, server-side).
+     *
+     * No principal check — this is a server-internal mutation path used
+     * by reconciliation jobs (Slack delivery status updates) and never
+     * exposed directly to user HTTP traffic. Phase 6c will retire the
+     * legacy method that called this; until then it is the only callable
+     * write-through for the existing reconciliation code.
+     *
+     * @param messageId - Message id to update
+     * @param patch - Shallow metadata patch to merge
+     * @returns The updated message DTO, or null if no such message exists
+     */
+    updateMessageMetadata(messageId, patch) {
+        const row = this.messages.updateMetadata(messageId, patch);
+        if (!row)
+            return null;
+        return this.toMessageDTO(row, []);
+    }
+    /**
+     * Phase 6.0 — replacement for the legacy
+     * `ChatService.getMessagesWithPendingSlackDelivery`. Returns the
+     * messages still marked `slackDeliveryStatus='pending'` within the
+     * caller-supplied lookback window, used by NotifyReconciliationService
+     * to retry stuck Slack deliveries.
+     *
+     * @param maxAgeMs - Lookback window in milliseconds
+     * @returns Pending-delivery messages, newest first, capped at MAX_LIMIT
+     */
+    findMessagesWithPendingSlackDelivery(maxAgeMs) {
+        const rows = this.messages.findPendingSlackDelivery(maxAgeMs);
+        return rows.map((r) => this.toMessageDTO(r, []));
+    }
+    /**
+     * Phase 6.0 — replacement for the legacy `ChatService.getStatistics`.
+     * Aggregate counts used by the boot-time telemetry and the
+     * admin/audit dashboards.
+     *
+     * @returns Active/archived channel counts plus total message count
+     */
+    getStatistics() {
+        const activeChannels = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM chat_channels WHERE archived_at IS NULL`)
+            .get().n;
+        const archivedChannels = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM chat_channels WHERE archived_at IS NOT NULL`)
+            .get().n;
+        return {
+            totalChannels: activeChannels + archivedChannels,
+            activeChannels,
+            archivedChannels,
+            totalMessages: this.messages.countAll(),
+        };
+    }
     // -------------------------------------------------------------------------
     // Channel operations
     // -------------------------------------------------------------------------
@@ -164,6 +240,354 @@ export class ChatV2Service {
         });
         return this.toChannelDTO(row);
     }
+    /**
+     * Phase B-2 (2026-05-17) — create a huddle (ad-hoc multi-agent group
+     * channel). Creates a `type='huddle'` channel row with no team
+     * binding, then inserts one row per member into
+     * `chat_channel_members`. The dispatcher uses that roster to fan out
+     * subsequent user messages to every member; agents whose session is
+     * in the outgoing message's `mentions[]` get a "must respond"
+     * prompt, others get an "optional" one.
+     *
+     * @param args - name, optional purpose, member roster, owning principal
+     * @returns The created huddle channel as a DTO, with `members` populated
+     * @throws {ChatError} `validation_error` (400) when name is empty/too long,
+     *   purpose too long, or memberSessions is empty / has too many entries.
+     */
+    createHuddle(args) {
+        const name = (args.name ?? '').trim();
+        if (name.length === 0) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'name is required');
+        }
+        if (name.length > this.config.maxChannelNameChars) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, `name exceeds ${this.config.maxChannelNameChars} characters`);
+        }
+        const purpose = args.purpose?.trim();
+        if (purpose && purpose.length > this.config.maxPurposeChars) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, `purpose exceeds ${this.config.maxPurposeChars} characters`);
+        }
+        // Dedupe + trim member sessions. We accept any non-empty trimmed
+        // string here — actual agent existence is validated by the
+        // dispatcher when it tries to resolve the session at fan-out time.
+        const seen = new Set();
+        const members = [];
+        for (const raw of args.memberSessions ?? []) {
+            const s = (raw ?? '').trim();
+            if (!s)
+                continue;
+            if (seen.has(s))
+                continue;
+            seen.add(s);
+            members.push(s);
+        }
+        if (members.length === 0) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'memberSessions must include at least one agent session');
+        }
+        // Defensive upper bound — a 200-member huddle would tax both the
+        // dispatcher fan-out and downstream rate limits. The cap can be
+        // raised when we have a real use case.
+        const MAX_HUDDLE_MEMBERS = 50;
+        if (members.length > MAX_HUDDLE_MEMBERS) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, `huddle exceeds the ${MAX_HUDDLE_MEMBERS}-member cap`);
+        }
+        const nowMs = this.now();
+        const row = this.channels.create({
+            // Huddle isn't 1:1-bound — keep agent_session empty (same convention
+            // as type='channel'). No team_id either: huddles are ad-hoc groups,
+            // not team-scoped surfaces.
+            agentSession: '',
+            ownerUserId: args.principal.userId,
+            name,
+            purpose: purpose || null,
+            type: 'huddle',
+            teamId: null,
+            projectId: null,
+            targetMemberId: null,
+            nowMs,
+        });
+        // Insert membership rows. INSERT OR IGNORE is defensive against the
+        // dedupe above getting bypassed (e.g., when callers reuse this
+        // method via the relay adapter with raw input).
+        const memberStmt = this.db.prepare(`INSERT OR IGNORE INTO chat_channel_members
+         (channel_id, member_session, joined_at)
+       VALUES (?, ?, ?)`);
+        const insertMany = this.db.transaction((rows) => {
+            for (const s of rows)
+                memberStmt.run(row.id, s, nowMs);
+        });
+        insertMany(members);
+        return this.toChannelDTO(row);
+    }
+    /**
+     * Phase B-2 — list the members of a huddle channel. Returns an empty
+     * array (not an error) for non-huddle channels so consumers can call
+     * this unconditionally during channel rendering.
+     *
+     * @param channelId - The channel to enumerate
+     * @param principal - The caller; used to verify ownership
+     * @returns Array of `{ sessionName, joinedAt }` rows
+     * @throws {ChatError} `not_found` (404) when the channel doesn't exist or
+     *   isn't owned by `principal`.
+     */
+    listHuddleMembers(channelId, principal) {
+        const row = this.requireOwnedChannel(channelId, principal);
+        if (row.type !== 'huddle')
+            return [];
+        return this.queryHuddleMembers(channelId);
+    }
+    /**
+     * Phase B-2 — dispatcher-facing roster lookup. Returns the session
+     * names of every member in a huddle, in `joined_at ASC` order.
+     * Unlike {@link listHuddleMembers} this is NOT principal-scoped:
+     * the dispatcher runs server-side and already holds the channel
+     * (it just persisted a message into it). Returns an empty array for
+     * non-huddle channels or unknown ids so the dispatcher's
+     * `members.length === 0` skip path stays clean.
+     *
+     * @param channelId - The huddle channel id
+     * @returns Array of agent session names
+     */
+    queryHuddleMembersForDispatch(channelId) {
+        return this.queryHuddleMembers(channelId).map((m) => m.sessionName);
+    }
+    /** Internal: read members straight from the DB (no ownership check). */
+    queryHuddleMembers(channelId) {
+        const rows = this.db
+            .prepare(`SELECT member_session AS sessionName, joined_at AS joinedAt
+           FROM chat_channel_members
+          WHERE channel_id = ?
+          ORDER BY joined_at ASC`)
+            .all(channelId);
+        return rows.map((r) => ({ sessionName: r.sessionName, joinedAt: r.joinedAt }));
+    }
+    /**
+     * Idempotent DM channel lookup-or-create for the /agents page.
+     *
+     * Returns the most-recent active DM channel owned by `principal.userId`
+     * and bound to `agentSession`; creates a new one when none exists. The
+     * caller is the human owner (auth principal), unlike
+     * {@link ensureChannelForLegacyConversation} which runs as `'system'`
+     * for server-internal bridge paths.
+     *
+     * Used by `POST /api/chat/channels/dm/ensure` so the /agents page can
+     * map "user clicked an agent in the directory" → "send/receive messages
+     * on this channel" without leaking duplicate DMs every time the page
+     * is reloaded.
+     *
+     * @param args - Lookup-or-create args
+     * @returns The channel DTO plus a `created` flag (true when a new row
+     *   was inserted; false when an existing row was reused).
+     * @throws {ChatError} `validation_error` (400) on empty `agentSession`
+     *   or oversize `name` / `purpose`.
+     */
+    ensureDmChannel(args) {
+        const agentSession = (args.agentSession ?? '').trim();
+        if (agentSession.length === 0) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'agentSession is required');
+        }
+        const existing = this.channels.findActiveDmByOwnerAndAgent(args.principal.userId, agentSession);
+        if (existing) {
+            return { channel: this.toChannelDTO(existing), created: false };
+        }
+        // Fall through to createChannel so the full validation + tenant
+        // checks (purpose length, name length, etc.) run consistently with
+        // the public POST /channels endpoint.
+        const channel = this.createChannel({
+            agentSession,
+            name: (args.name ?? agentSession).trim(),
+            purpose: args.purpose,
+            principal: args.principal,
+            type: 'dm',
+        });
+        return { channel, created: true };
+    }
+    /**
+     * Server-internal idempotent helper used by migration / bridge code to
+     * map a legacy conversationId (e.g. `slack-D0AC7-1234`, `web-conv-abc`)
+     * onto a chat-v2 channel row with the conversationId as the primary key.
+     *
+     * Unlike {@link createChannel}, this method:
+     *   - Returns the existing channel when one already lives at the given
+     *     id — idempotent for runtimes that call it before every recordTurn.
+     *   - Accepts a synthetic owner (`'system'`) for paths where no human
+     *     principal is on the call stack (PTY finish hooks, Slack inbound
+     *     bridge, in-process runtime auto-route).
+     *   - Sets `type='dm'` so the channel matches the conversation-per-thread
+     *     legacy model the user approved (spec Option B).
+     *
+     * The `agent_already_bound` failure mode that existed in chat-v2 Phase A
+     * does not apply — the `uq_channel_agent_dm_active` index was dropped
+     * per the unified-chat-message-store spec exactly so this helper can
+     * lazy-create N concurrent DM channels for a single agent.
+     *
+     * @param args - Legacy bridge args
+     * @returns The existing or freshly created channel DTO
+     * @throws {ChatError} `validation_error` on missing id / agentSession
+     *
+     * @example
+     * ```typescript
+     * // Called from `routeInProcessResponseToChat` before `recordTurn`:
+     * const channel = chatV2.ensureChannelForLegacyConversation({
+     *   conversationId: 'slack-D0AC7-1700000000.000111',
+     *   agentSession: 'crewly-orc',
+     * });
+     * chatV2.recordTurn({ channelId: channel.id, ... });
+     * ```
+     */
+    ensureChannelForLegacyConversation(args) {
+        const conversationId = (args.conversationId ?? '').trim();
+        if (conversationId.length === 0) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'conversationId is required');
+        }
+        const agentSession = (args.agentSession ?? '').trim();
+        if (agentSession.length === 0) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'agentSession is required');
+        }
+        const existing = this.channels.getById(conversationId);
+        if (existing) {
+            return this.toChannelDTO(existing);
+        }
+        const name = (args.name ?? conversationId).trim();
+        const ownerUserId = (args.ownerUserId ?? 'system').trim();
+        const row = this.channels.create({
+            id: conversationId,
+            agentSession,
+            ownerUserId,
+            name,
+            purpose: null,
+            type: 'dm',
+            teamId: null,
+            projectId: null,
+            targetMemberId: null,
+            nowMs: this.now(),
+        });
+        return this.toChannelDTO(row);
+    }
+    /**
+     * Phase 5 of unified-chat-message-store spec — idempotent import of one
+     * legacy conversation file (`~/.crewly/chat/<conversationId>.json`)
+     * into the chat-v2 SQLite store. Each legacy message becomes one
+     * `chat_messages` row keyed by a deterministic `clientMessageId` so
+     * re-running the import is safe — the underlying `MessageStore`
+     * dedups on `(channel_id, clientMessageId)`.
+     *
+     * Designed as a service method (not a free function) so the CLI
+     * migration script can call it per file and so callers can unit-test
+     * the mapping in isolation.
+     *
+     * The mapping:
+     *   - `conversation.id` → `chat_channels.id` (via
+     *     {@link ensureChannelForLegacyConversation}). `agentSession`
+     *     defaults to `'crewly-orc'` because every legacy conversation was
+     *     a DM between the user and the orchestrator.
+     *   - `messages[].from.type === 'user'` → `senderType: 'user'`
+     *   - `messages[].from.type === 'orchestrator'` (or 'agent') →
+     *     `senderType: 'agent'`, `senderId: 'crewly-orc'`
+     *   - Anything else → `senderType: 'system'`, `senderId: 'system'`
+     *   - `messages[].id` → `clientMessageId = 'legacy-' + msg.id` for
+     *     stable idempotency across re-runs.
+     *   - `messages[].metadata.source` (legacy slack/web) → carried
+     *     through; `recordTurn`'s required outer `metadata.source` is set
+     *     to `'system'` to identify the migration as the writer.
+     *
+     * @param input - Parsed legacy JSON (the entire file body)
+     * @returns Per-message outcome (imported vs deduped) + the channel id
+     *
+     * @example
+     * ```typescript
+     * const json = JSON.parse(await readFile(filePath, 'utf-8'));
+     * const result = chatV2.importLegacyConversation(json);
+     * console.log(`Imported ${result.imported} new, ${result.deduped} dedup`);
+     * ```
+     */
+    importLegacyConversation(input) {
+        if (!input?.conversation?.id) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'legacy conversation.id is required');
+        }
+        if (!Array.isArray(input.messages)) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'legacy messages must be an array');
+        }
+        const channel = this.ensureChannelForLegacyConversation({
+            conversationId: input.conversation.id,
+            agentSession: 'crewly-orc',
+            name: input.conversation.id,
+        });
+        let imported = 0;
+        let deduped = 0;
+        let skipped = 0;
+        const skippedReasons = [];
+        for (let i = 0; i < input.messages.length; i++) {
+            const msg = input.messages[i];
+            if (!msg?.id) {
+                skipped++;
+                skippedReasons.push({ index: i, reason: 'missing-id', id: msg?.id });
+                continue;
+            }
+            if (typeof msg.content !== 'string' || msg.content.length === 0) {
+                skipped++;
+                skippedReasons.push({ index: i, reason: 'empty-content', id: msg.id });
+                continue;
+            }
+            const fromType = (msg.from?.type ?? '').toLowerCase();
+            let senderType;
+            let senderId;
+            if (fromType === 'user') {
+                senderType = 'user';
+                senderId =
+                    (typeof msg.metadata?.userId === 'string' && msg.metadata.userId) ||
+                        msg.from?.name ||
+                        'legacy-user';
+            }
+            else if (fromType === 'agent' || fromType === 'orchestrator') {
+                senderType = 'agent';
+                senderId = 'crewly-orc';
+            }
+            else {
+                senderType = 'system';
+                senderId = 'system';
+            }
+            const result = this.recordTurn({
+                channelId: channel.id,
+                senderType,
+                senderId,
+                content: msg.content,
+                clientMessageId: `legacy-${msg.id}`,
+                metadata: {
+                    source: 'system',
+                    // Carry through legacy metadata for forensic completeness —
+                    // future audits can still see "this row was originally a slack
+                    // inbound" via metadata.legacySource etc.
+                    legacySource: typeof msg.metadata?.source === 'string' ? msg.metadata.source : undefined,
+                    legacyMessageId: msg.id,
+                    legacyTimestamp: msg.timestamp,
+                },
+            });
+            if (result.deduped) {
+                deduped++;
+            }
+            else {
+                imported++;
+            }
+        }
+        if (skipped > 0) {
+            // Surface malformed legacy rows so the migration operator can
+            // decide whether to repair the source JSON before re-running, or
+            // accept that some history is unrecoverable. Without this log the
+            // earlier silent-skip behavior turned data-loss into a counter
+            // mismatch that nobody noticed. ChatV2Service has no injected
+            // logger; the migration runs as a CLI script so console output
+            // is the right sink.
+            // eslint-disable-next-line no-console
+            console.warn(`[chat-v2] importLegacyConversation: skipped ${skipped}/${input.messages.length} malformed row(s) in ${input.conversation.id}`, {
+                channelId: channel.id,
+                skipped,
+                totalRows: input.messages.length,
+                reasons: skippedReasons.slice(0, 10),
+                truncated: skippedReasons.length > 10,
+            });
+        }
+        return { channelId: channel.id, imported, deduped, skipped };
+    }
     /**
      * List channels owned by the caller.
      *
@@ -220,6 +644,87 @@ export class ChatV2Service {
         this.requireOwnedChannel(channelId, principal);
         return this.channels.archive(channelId, this.now());
     }
+    /**
+     * Phase 6.0b — clear the `archived_at` flag on a channel. Inverse of
+     * {@link archiveChannel}; required to retire the legacy
+     * `unarchiveConversation` route.
+     *
+     * @param channelId - The channel to unarchive
+     * @param principal - Auth principal (must own the channel)
+     * @returns True if newly unarchived, false if already active
+     * @throws {ChatError} `channel_not_found` (404)
+     */
+    unarchiveChannel(channelId, principal) {
+        this.requireOwnedChannel(channelId, principal);
+        return this.channels.unarchive(channelId);
+    }
+    /**
+     * Phase 6.0b — rename a channel. Replaces the legacy
+     * `updateConversationTitle` route. Server validates the same name
+     * constraints as `createChannel`.
+     *
+     * @param channelId - The channel to rename
+     * @param name - New name (trimmed, ≤ maxChannelNameChars)
+     * @param principal - Auth principal (must own the channel)
+     * @returns The renamed channel DTO
+     * @throws {ChatError} `validation_error` (400) on empty / oversize name,
+     *                    `channel_not_found` (404)
+     */
+    renameChannel(channelId, name, principal) {
+        const trimmed = (name ?? '').trim();
+        if (trimmed.length === 0) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'name is required');
+        }
+        if (trimmed.length > this.config.maxChannelNameChars) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, `name exceeds ${this.config.maxChannelNameChars} characters`);
+        }
+        const row = this.requireOwnedChannel(channelId, principal);
+        this.channels.rename(channelId, trimmed);
+        return this.toChannelDTO({ ...row, name: trimmed });
+    }
+    /**
+     * Phase 6.0b — hard-delete a channel and all its messages. Distinct
+     * from {@link archiveChannel} (soft delete). Replaces the legacy
+     * `deleteConversation` route. Uses SQLite FK cascade so the row
+     * deletion atomically removes child messages.
+     *
+     * @param channelId - The channel to delete
+     * @param principal - Auth principal (must own the channel)
+     * @returns True if removed, false if the channel didn't exist
+     * @throws {ChatError} `channel_not_found` (404)
+     */
+    deleteChannel(channelId, principal) {
+        this.requireOwnedChannel(channelId, principal);
+        return this.channels.hardDelete(channelId);
+    }
+    /**
+     * Phase 6.0b — delete all messages in a channel while keeping the
+     * channel row. Replaces the legacy `clearConversation` route. Useful
+     * when the user wants a "fresh start" without losing the channel
+     * itself (and its bookkeeping like `agent_session` binding).
+     *
+     * @param channelId - The channel to clear
+     * @param principal - Auth principal (must own the channel)
+     * @returns Number of messages deleted
+     * @throws {ChatError} `channel_not_found` (404)
+     */
+    clearChannel(channelId, principal) {
+        this.requireOwnedChannel(channelId, principal);
+        return this.messages.deleteAllByChannel(channelId);
+    }
+    /**
+     * Phase 6.0b — count messages in a single channel. Replaces the
+     * legacy `getMessageCount` filtered to one conversation.
+     *
+     * @param channelId - The channel to count
+     * @param principal - Auth principal (must own the channel)
+     * @returns Message count (0 for empty channels)
+     * @throws {ChatError} `channel_not_found` (404)
+     */
+    countChannelMessages(channelId, principal) {
+        this.requireOwnedChannel(channelId, principal);
+        return this.messages.count(channelId);
+    }
     // -------------------------------------------------------------------------
     // Message operations
     // -------------------------------------------------------------------------
@@ -268,7 +773,112 @@ export class ChatV2Service {
             threadId,
             nowMs: this.now(),
         });
-        return this.toMessageDTO(persisted, args.attachments ?? []);
+        const dto = this.toMessageDTO(persisted, args.attachments ?? []);
+        // Phase 6c: broadcast so the WebSocket gateway (and any other
+        // in-process subscribers) can fan the new message out to connected
+        // clients. The legacy ChatService.EventEmitter contract is now
+        // owned by chat-v2 directly.
+        this.emit('chat_message', dto);
+        return dto;
+    }
+    /**
+     * Canonical server-internal write entry for chat messages.
+     *
+     * Unlike {@link sendMessage}, which derives `sender_type` / `sender_id`
+     * from an authenticated request principal, `recordTurn` is the path
+     * used by runtimes, controllers, and bridges that have already
+     * resolved exactly who the sender is — e.g.:
+     *
+     *   - In-process agent runtime finishing a turn
+     *   - PTY runtime emitting a complete reply
+     *   - Slack inbound bridge persisting a user DM
+     *   - `/slack/send` controller persisting the agent's outbound reply
+     *
+     * Per spec `2026-05-14-unified-chat-message-store.md`, every chat
+     * write in the system funnels through this method. No caller should
+     * write to {@link MessageStore} directly; no caller should reach
+     * into legacy {@link ChatService} (Phase 6 retires it).
+     *
+     * Idempotent via `clientMessageId` — the underlying store dedups by
+     * `(channel_id, clientMessageId)` and returns the existing row with
+     * `deduped=true` instead of inserting a duplicate.
+     *
+     * @param input - Turn payload (channel, sender, content, metadata)
+     * @returns The persisted message DTO + dedupe flag
+     * @throws {ChatError} `channel_not_found` (404) if the channel is missing
+     * @throws {ChatError} `validation_error` (400) on empty content or invalid contentType
+     * @throws {ChatError} `payload_too_large` (413) if content exceeds maxMessageBytes
+     *
+     * @example
+     * ```typescript
+     * const { message, deduped } = chatV2.recordTurn({
+     *   channelId: 'slack-D0AC7-1234',
+     *   senderType: 'agent',
+     *   senderId: 'crewly-orc',
+     *   content: 'Hello!',
+     *   clientMessageId: 'agent-finish-2026-05-14T22:30:00Z',
+     *   metadata: {
+     *     source: 'in-process-runtime',
+     *     runtime: 'crewly-agent',
+     *     slackChannelId: 'D0AC7',
+     *     slackThreadTs: '1234',
+     *   },
+     * });
+     * ```
+     */
+    recordTurn(input) {
+        const content = input.content ?? '';
+        if (content.length === 0) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'content is required');
+        }
+        const byteLen = Buffer.byteLength(content, 'utf-8');
+        if (byteLen > this.config.maxMessageBytes) {
+            throw new ChatError(CHAT_ERROR_CODES.PAYLOAD_TOO_LARGE, 413, `content exceeds max bytes (${this.config.maxMessageBytes})`, { maxBytes: this.config.maxMessageBytes, yourBytes: byteLen });
+        }
+        const contentType = input.contentType ?? 'markdown';
+        if (!CHAT_CONTENT_TYPES.includes(contentType)) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, `unknown contentType: ${contentType}`);
+        }
+        if (!CHAT_SENDER_TYPES.includes(input.senderType)) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, `unknown senderType: ${input.senderType}`);
+        }
+        if (!input.senderId || input.senderId.length === 0) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'senderId is required');
+        }
+        const mentions = this.validateMentions(input.mentions);
+        const threadId = this.validateThreadId(input.threadId, input.channelId);
+        // `metadata.source` is the audit-trail discriminator that lets
+        // future tooling tell "this message came from PTY" vs "from
+        // in-process runtime" vs "from /slack/send" without parsing
+        // content. Spec success criterion #4 depends on this tag being
+        // present for every recordTurn caller.
+        const metadata = { ...(input.metadata ?? {}) };
+        if (!metadata.source) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, 'metadata.source is required for recordTurn (audit trail)');
+        }
+        if (!RECORD_TURN_SOURCES.includes(metadata.source)) {
+            throw new ChatError(CHAT_ERROR_CODES.VALIDATION, 400, `unknown metadata.source: ${String(metadata.source)}`, { allowed: RECORD_TURN_SOURCES });
+        }
+        const { row: persisted, deduped } = this.messages.insert({
+            channelId: input.channelId,
+            senderType: input.senderType,
+            senderId: input.senderId,
+            content,
+            contentType,
+            clientMessageId: input.clientMessageId,
+            mentions,
+            threadId,
+            metadata,
+            nowMs: this.now(),
+        });
+        const dto = this.toMessageDTO(persisted, []);
+        // Phase 6c: emit only for freshly inserted rows. Skipping dedup hits
+        // prevents replay-loop subscribers from seeing the same message twice
+        // on idempotent retries.
+        if (!deduped) {
+            this.emit('chat_message', dto);
+        }
+        return { message: dto, deduped };
     }
     /**
      * Phase A — validate the mentions array passed to sendMessage.
@@ -433,6 +1043,12 @@ export class ChatV2Service {
             teamId: row.team_id ?? undefined,
             projectId: row.project_id ?? undefined,
             targetMemberId: row.target_member_id ?? undefined,
+            // Phase B-2: huddle channels surface their roster inline so the
+            // Portal can render member avatars without a second round-trip.
+            // Non-huddle rows leave this undefined.
+            ...(channelType === 'huddle'
+                ? { members: this.queryHuddleMembers(row.id) }
+                : {}),
         };
     }
     /** Map a message row to the wire DTO. Attachments passed in by the caller. */