@openparachute/agent 0.1.0

package/src/modules/permissions/channel-approval.test.ts

@@ -0,0 +1,389 @@
+/**
+ * Integration tests for the unknown-channel registration flow (ACTION-ITEMS
+ * item 22).
+ *
+ * Covers:
+ *  - Mention on an unwired channel fires an owner-approval card
+ *  - DM on an unwired channel fires a card (engage_mode will default to pattern='.')
+ *  - In-flight dedup: second mention while a card is pending doesn't spam
+ *  - Approve: wiring created with correct defaults, triggering sender added
+ *    as member, replay wakes the container
+ *  - Deny: messaging_groups.denied_at set, future mentions drop silently
+ *  - Unauthorized clicker is rejected (same pattern as sender-approval)
+ *  - No-owner install: no card, no row
+ *  - No agent groups configured: no card, no row
+ */
+import fs from 'fs';
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+
+import { initTestDb, closeDb, runMigrations } from '../../db/index.js';
+import { createAgentGroup } from '../../db/agent-groups.js';
+import { createMessagingGroup, getMessagingGroupByPlatform } from '../../db/messaging-groups.js';
+import { upsertUser } from './db/users.js';
+import { grantRole } from './db/user-roles.js';
+
+// Mock container runner — prevent actual docker spawn.
+vi.mock('../../container-runner.js', () => ({
+  wakeContainer: vi.fn().mockResolvedValue(undefined),
+  isContainerRunning: vi.fn().mockReturnValue(false),
+  getActiveContainerCount: vi.fn().mockReturnValue(0),
+  killContainer: vi.fn(),
+}));
+
+// Mock delivery adapter.
+const deliverMock = vi.fn().mockResolvedValue('plat-msg-id');
+vi.mock('../../delivery.js', () => ({
+  getDeliveryAdapter: () => ({ deliver: deliverMock }),
+}));
+
+// Mock ensureUserDm — look up the owner's preconfigured DM row instead of
+// hitting a real openDM RPC.
+vi.mock('./user-dm.js', () => ({
+  ensureUserDm: vi.fn(async (userId: string) => {
+    const { getDb } = await import('../../db/connection.js');
+    const row = getDb()
+      .prepare(
+        `SELECT mg.* FROM messaging_groups mg
+           JOIN user_dms ud ON ud.messaging_group_id = mg.id
+          WHERE ud.user_id = ?`,
+      )
+      .get(userId);
+    return row;
+  }),
+}));
+
+vi.mock('../../config.js', async () => {
+  const actual = await vi.importActual('../../config.js');
+  return { ...actual, DATA_DIR: '/tmp/paraclaw-test-channel-approval' };
+});
+
+const TEST_DIR = '/tmp/paraclaw-test-channel-approval';
+
+function now() {
+  return new Date().toISOString();
+}
+
+beforeEach(async () => {
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+  const db = initTestDb();
+  runMigrations(db);
+
+  await import('./index.js'); // register hooks
+
+  // Base fixtures: one agent group + owner with a DM on 'telegram'.
+  createAgentGroup({ id: 'ag-1', name: 'Andy', folder: 'andy', agent_provider: null, created_at: now() });
+
+  upsertUser({ id: 'telegram:owner', kind: 'telegram', display_name: 'Owner', created_at: now() });
+  grantRole({
+    user_id: 'telegram:owner',
+    role: 'owner',
+    agent_group_id: null,
+    granted_by: null,
+    granted_at: now(),
+  });
+
+  // Pre-seed owner's DM messaging group + user_dms mapping.
+  createMessagingGroup({
+    id: 'mg-dm-owner',
+    channel_type: 'telegram',
+    platform_id: 'dm-owner',
+    name: 'Owner DM',
+    is_group: 0,
+    unknown_sender_policy: 'public',
+    created_at: now(),
+  });
+  const { getDb } = await import('../../db/connection.js');
+  getDb()
+    .prepare(
+      `INSERT INTO user_dms (user_id, channel_type, messaging_group_id, resolved_at)
+       VALUES (?, ?, ?, ?)`,
+    )
+    .run('telegram:owner', 'telegram', 'mg-dm-owner', now());
+
+  deliverMock.mockClear();
+});
+
+afterEach(() => {
+  closeDb();
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+});
+
+function groupMention(platformId: string, text = '@bot hello') {
+  return {
+    channelType: 'telegram',
+    platformId,
+    threadId: 'thread-1', // non-null → is_group=true per channel-approval default-picker logic
+    message: {
+      id: `msg-${Math.random().toString(36).slice(2, 8)}`,
+      kind: 'chat' as const,
+      content: JSON.stringify({ senderId: 'caller', senderName: 'Caller', text }),
+      timestamp: now(),
+      isMention: true,
+    },
+  };
+}
+
+function dmEvent(platformId: string, text = 'hello') {
+  return {
+    channelType: 'telegram',
+    platformId,
+    threadId: null,
+    message: {
+      id: `msg-${Math.random().toString(36).slice(2, 8)}`,
+      kind: 'chat' as const,
+      content: JSON.stringify({ senderId: 'stranger', senderName: 'Stranger', text }),
+      timestamp: now(),
+      isMention: true, // DM bridge sets isMention=true
+    },
+  };
+}
+
+describe('unknown-channel registration flow', () => {
+  it('delivers an approval card on mention into an unwired group', async () => {
+    const { routeInbound } = await import('../../router.js');
+    await routeInbound(groupMention('chat-new'));
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(deliverMock).toHaveBeenCalledTimes(1);
+    const [channel, platformId, thread, kind, content] = deliverMock.mock.calls[0];
+    expect(channel).toBe('telegram');
+    expect(platformId).toBe('dm-owner'); // delivered to owner's DM
+    expect(thread).toBeNull();
+    expect(kind).toBe('chat-sdk');
+    const payload = JSON.parse(content as string);
+    expect(payload.type).toBe('ask_question');
+    // Card names the target agent so the owner knows what they're wiring to.
+    expect(payload.question).toContain('Andy');
+
+    const { getDb } = await import('../../db/connection.js');
+    const rows = getDb().prepare('SELECT * FROM pending_channel_approvals').all() as Array<{
+      messaging_group_id: string;
+    }>;
+    expect(rows).toHaveLength(1);
+  });
+
+  it('delivers a card on DM too (non-threaded event)', async () => {
+    const { routeInbound } = await import('../../router.js');
+    await routeInbound(dmEvent('dm-new-user'));
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(deliverMock).toHaveBeenCalledTimes(1);
+    const { getDb } = await import('../../db/connection.js');
+    const count = (getDb().prepare('SELECT COUNT(*) AS c FROM pending_channel_approvals').get() as { c: number }).c;
+    expect(count).toBe(1);
+  });
+
+  it('dedups a second mention while the card is pending', async () => {
+    const { routeInbound } = await import('../../router.js');
+    await routeInbound(groupMention('chat-busy'));
+    await new Promise((r) => setTimeout(r, 10));
+    await routeInbound(groupMention('chat-busy', '@bot still here'));
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(deliverMock).toHaveBeenCalledTimes(1);
+    const { getDb } = await import('../../db/connection.js');
+    const count = (getDb().prepare('SELECT COUNT(*) AS c FROM pending_channel_approvals').get() as { c: number }).c;
+    expect(count).toBe(1);
+  });
+
+  it('approve → creates wiring, admits triggering sender, replays', async () => {
+    const { routeInbound } = await import('../../router.js');
+    const { getResponseHandlers } = await import('../../response-registry.js');
+    const { wakeContainer } = await import('../../container-runner.js');
+    (wakeContainer as unknown as ReturnType<typeof vi.fn>).mockClear();
+
+    await routeInbound(groupMention('chat-approve'));
+    await new Promise((r) => setTimeout(r, 10));
+
+    const { getDb } = await import('../../db/connection.js');
+    const pending = getDb().prepare('SELECT messaging_group_id FROM pending_channel_approvals').get() as {
+      messaging_group_id: string;
+    };
+    expect(pending).toBeDefined();
+
+    // Owner clicks approve.
+    for (const handler of getResponseHandlers()) {
+      const claimed = await handler({
+        questionId: pending.messaging_group_id,
+        value: 'approve',
+        userId: 'owner', // raw platform id — handler namespaces it
+        channelType: 'telegram',
+        platformId: 'dm-owner',
+        threadId: null,
+      });
+      if (claimed) break;
+    }
+
+    // Wiring created with MVP defaults.
+    const mga = getDb()
+      .prepare('SELECT * FROM messaging_group_agents WHERE messaging_group_id = ?')
+      .get(pending.messaging_group_id) as {
+      engage_mode: string;
+      engage_pattern: string | null;
+      sender_scope: string;
+      ignored_message_policy: string;
+      agent_group_id: string;
+    };
+    expect(mga).toBeDefined();
+    expect(mga.engage_mode).toBe('mention-sticky'); // group (threadId != null)
+    expect(mga.engage_pattern).toBeNull();
+    expect(mga.sender_scope).toBe('known');
+    expect(mga.ignored_message_policy).toBe('accumulate');
+    expect(mga.agent_group_id).toBe('ag-1');
+
+    // Triggering sender auto-admitted so sender_scope='known' doesn't
+    // bounce the replay into sender-approval.
+    const member = getDb()
+      .prepare('SELECT 1 AS x FROM agent_group_members WHERE user_id = ? AND agent_group_id = ?')
+      .get('telegram:caller', 'ag-1');
+    expect(member).toBeDefined();
+
+    // Pending row cleared and container woken via replay.
+    const stillPending = (getDb().prepare('SELECT COUNT(*) AS c FROM pending_channel_approvals').get() as { c: number })
+      .c;
+    expect(stillPending).toBe(0);
+    expect(wakeContainer).toHaveBeenCalled();
+  });
+
+  it('approve on a DM wires with pattern="." defaults', async () => {
+    const { routeInbound } = await import('../../router.js');
+    const { getResponseHandlers } = await import('../../response-registry.js');
+
+    await routeInbound(dmEvent('dm-approve-user'));
+    await new Promise((r) => setTimeout(r, 10));
+
+    const { getDb } = await import('../../db/connection.js');
+    const pending = getDb().prepare('SELECT messaging_group_id FROM pending_channel_approvals').get() as {
+      messaging_group_id: string;
+    };
+
+    for (const handler of getResponseHandlers()) {
+      const claimed = await handler({
+        questionId: pending.messaging_group_id,
+        value: 'approve',
+        userId: 'owner',
+        channelType: 'telegram',
+        platformId: 'dm-owner',
+        threadId: null,
+      });
+      if (claimed) break;
+    }
+
+    const mga = getDb()
+      .prepare('SELECT engage_mode, engage_pattern FROM messaging_group_agents WHERE messaging_group_id = ?')
+      .get(pending.messaging_group_id) as { engage_mode: string; engage_pattern: string };
+    expect(mga.engage_mode).toBe('pattern');
+    expect(mga.engage_pattern).toBe('.');
+  });
+
+  it('deny → sets denied_at; future mentions drop silently without a second card', async () => {
+    const { routeInbound } = await import('../../router.js');
+    const { getResponseHandlers } = await import('../../response-registry.js');
+
+    await routeInbound(groupMention('chat-deny'));
+    await new Promise((r) => setTimeout(r, 10));
+    const { getDb } = await import('../../db/connection.js');
+    const pending = getDb().prepare('SELECT messaging_group_id FROM pending_channel_approvals').get() as {
+      messaging_group_id: string;
+    };
+
+    for (const handler of getResponseHandlers()) {
+      const claimed = await handler({
+        questionId: pending.messaging_group_id,
+        value: 'reject',
+        userId: 'owner',
+        channelType: 'telegram',
+        platformId: 'dm-owner',
+        threadId: null,
+      });
+      if (claimed) break;
+    }
+
+    // denied_at set, pending row cleared, no wiring.
+    const mg = getMessagingGroupByPlatform('telegram', 'chat-deny');
+    expect(mg?.denied_at).not.toBeNull();
+    expect(mg?.denied_at).toBeTruthy();
+    const mgaCount = (
+      getDb()
+        .prepare('SELECT COUNT(*) AS c FROM messaging_group_agents WHERE messaging_group_id = ?')
+        .get(pending.messaging_group_id) as { c: number }
+    ).c;
+    expect(mgaCount).toBe(0);
+
+    // A follow-up mention on the denied channel: no new card, no new pending row.
+    deliverMock.mockClear();
+    await routeInbound(groupMention('chat-deny', '@bot please'));
+    await new Promise((r) => setTimeout(r, 10));
+    expect(deliverMock).not.toHaveBeenCalled();
+    const stillPending = (getDb().prepare('SELECT COUNT(*) AS c FROM pending_channel_approvals').get() as { c: number })
+      .c;
+    expect(stillPending).toBe(0);
+  });
+
+  it('rejects clicks from an unauthorized user (prevents self-admit via forwarded card)', async () => {
+    const { routeInbound } = await import('../../router.js');
+    const { getResponseHandlers } = await import('../../response-registry.js');
+
+    await routeInbound(groupMention('chat-unauth'));
+    await new Promise((r) => setTimeout(r, 10));
+    const { getDb } = await import('../../db/connection.js');
+    const pending = getDb().prepare('SELECT messaging_group_id FROM pending_channel_approvals').get() as {
+      messaging_group_id: string;
+    };
+
+    for (const handler of getResponseHandlers()) {
+      const claimed = await handler({
+        questionId: pending.messaging_group_id,
+        value: 'approve',
+        userId: 'random-bystander',
+        channelType: 'telegram',
+        platformId: 'dm-random',
+        threadId: null,
+      });
+      if (claimed) break;
+    }
+
+    // No wiring created, pending row preserved so a real approver can act on it.
+    const mgaCount = (
+      getDb()
+        .prepare('SELECT COUNT(*) AS c FROM messaging_group_agents WHERE messaging_group_id = ?')
+        .get(pending.messaging_group_id) as { c: number }
+    ).c;
+    expect(mgaCount).toBe(0);
+    const stillPending = (getDb().prepare('SELECT COUNT(*) AS c FROM pending_channel_approvals').get() as { c: number })
+      .c;
+    expect(stillPending).toBe(1);
+  });
+});
+
+describe('no-owner / no-agent failure modes', () => {
+  it('no owner → no card, no pending row (fresh-install bootstrap path)', async () => {
+    // Wipe the owner grant set up in the outer beforeEach.
+    const { getDb } = await import('../../db/connection.js');
+    getDb().prepare('DELETE FROM user_roles').run();
+
+    const { routeInbound } = await import('../../router.js');
+    await routeInbound(groupMention('chat-noowner'));
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(deliverMock).not.toHaveBeenCalled();
+    const count = (getDb().prepare('SELECT COUNT(*) AS c FROM pending_channel_approvals').get() as { c: number }).c;
+    expect(count).toBe(0);
+  });
+
+  it('no agent groups → no card, no pending row', async () => {
+    const { getDb } = await import('../../db/connection.js');
+    // Drop foreign-key-dependent rows first, then the agent group itself.
+    getDb().prepare('DELETE FROM user_roles').run();
+    getDb().prepare('DELETE FROM agent_groups').run();
+
+    const { routeInbound } = await import('../../router.js');
+    await routeInbound(groupMention('chat-noagent'));
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(deliverMock).not.toHaveBeenCalled();
+    const count = (getDb().prepare('SELECT COUNT(*) AS c FROM pending_channel_approvals').get() as { c: number }).c;
+    expect(count).toBe(0);
+  });
+});

package/src/modules/permissions/channel-approval.ts

@@ -0,0 +1,188 @@
+/**
+ * Unknown-channel registration flow.
+ *
+ * When the router hits an unwired messaging group AND the message was
+ * addressed to the bot (SDK-confirmed mention or DM), it calls
+ * `requestChannelApproval` instead of silently dropping. The flow:
+ *
+ *   1. Pick the target agent group we'd wire to (MVP: first by name).
+ *      Multi-agent picker is a follow-up — see ACTION-ITEMS.
+ *   2. Pick an eligible approver (owner / admin) and a reachable DM for
+ *      them, reusing the same primitives the sender-approval flow uses.
+ *   3. Deliver an Approve / Ignore card that names the target agent
+ *      explicitly so the owner knows what they're wiring to.
+ *   4. Record a `pending_channel_approvals` row holding the original event
+ *      so it can be re-routed on approve.
+ *
+ * On approve (handler in index.ts):
+ *   - Create `messaging_group_agents` with MVP defaults
+ *     (mention-sticky for groups / pattern='.' for DMs,
+ *      sender_scope='known', ignored_message_policy='accumulate')
+ *   - Add the triggering sender to `agent_group_members` so sender_scope
+ *     doesn't bounce the replayed message into a sender-approval cascade
+ *   - Delete the pending row, replay the original event
+ *
+ * On ignore:
+ *   - Set `messaging_groups.denied_at = now()` so the router stops
+ *     escalating on this channel until an admin explicitly re-wires
+ *   - Delete the pending row
+ *
+ * Dedup: `pending_channel_approvals` PK on messaging_group_id. Second
+ * mention while pending silently dropped.
+ *
+ * Failure modes (log + no row, so a future attempt can try again):
+ *   - No agent groups exist (install never set up a first agent).
+ *   - No eligible approver in user_roles (no owner yet).
+ *   - Approver has no reachable DM.
+ *   - Delivery adapter missing.
+ */
+import { normalizeOptions, type RawOption } from '../../channels/ask-question.js';
+import { getAllAgentGroups } from '../../db/agent-groups.js';
+import { getMessagingGroup } from '../../db/messaging-groups.js';
+import { getDeliveryAdapter } from '../../delivery.js';
+import { log } from '../../log.js';
+import { decodePlatformIdAs } from '../../platform-id.js';
+import type { InboundEvent } from '../../channels/adapter.js';
+import { appendFallbackNotice, pickApprovalDelivery, pickApprover } from '../approvals/primitive.js';
+import { createPendingChannelApproval, hasInFlightChannelApproval } from './db/pending-channel-approvals.js';
+
+const APPROVAL_OPTIONS: RawOption[] = [
+  { label: 'Approve', selectedLabel: '✅ Wired', value: 'approve' },
+  { label: 'Ignore', selectedLabel: '🙅 Ignored', value: 'reject' },
+];
+
+export interface RequestChannelApprovalInput {
+  messagingGroupId: string;
+  event: InboundEvent;
+}
+
+export async function requestChannelApproval(input: RequestChannelApprovalInput): Promise<void> {
+  const { messagingGroupId, event } = input;
+
+  // In-flight dedup: don't spam the owner if the same unwired channel
+  // gets more mentions / DMs while a card is already pending.
+  if (hasInFlightChannelApproval(messagingGroupId)) {
+    log.debug('Channel registration already in flight — dropping retry', {
+      messagingGroupId,
+    });
+    return;
+  }
+
+  // MVP: pick the first agent group by name. Multi-agent systems will get
+  // a richer card later (user picks the target from a list).
+  const agentGroups = getAllAgentGroups();
+  if (agentGroups.length === 0) {
+    log.warn('Channel registration skipped — no agent groups configured. Run /init-first-agent.', {
+      messagingGroupId,
+    });
+    return;
+  }
+  const target = agentGroups[0];
+
+  // pickApprover takes the target agent group's id — gets scoped admins +
+  // global admins + owners. For fresh installs with only an owner, the
+  // owner is returned.
+  const approvers = pickApprover(target.id);
+  if (approvers.length === 0) {
+    log.warn('Channel registration skipped — no owner or admin configured', {
+      messagingGroupId,
+      targetAgentGroupId: target.id,
+    });
+    return;
+  }
+
+  const originMg = getMessagingGroup(messagingGroupId);
+  const originChannelType = originMg?.channel_type ?? '';
+  const originBotId = originMg ? decodePlatformIdAs(originMg.platform_id, 'v2').botId : null;
+  const delivery = await pickApprovalDelivery(approvers, originChannelType, originBotId);
+  if (!delivery) {
+    log.warn('Channel registration skipped — no DM channel for any approver', {
+      messagingGroupId,
+      targetAgentGroupId: target.id,
+    });
+    return;
+  }
+
+  const isGroup = event.message?.isGroup ?? originMg?.is_group === 1;
+
+  // Extract sender name from the event content for a human-readable card.
+  let senderName: string | undefined;
+  try {
+    const parsed = JSON.parse(event.message.content) as Record<string, unknown>;
+    senderName = (parsed.senderName ?? parsed.sender) as string | undefined;
+  } catch {
+    // non-critical — fall through to generic wording
+  }
+
+  const title = isGroup ? '📣 Bot mentioned in new chat' : '💬 New direct message';
+  const question = isGroup
+    ? senderName
+      ? `${senderName} mentioned your agent in a ${originChannelType} channel. Wire it to ${target.name} and let it engage?`
+      : `Your agent was mentioned in a ${originChannelType} channel. Wire it to ${target.name} and let it engage?`
+    : senderName
+      ? `${senderName} DM'd your agent on ${originChannelType}. Wire it to ${target.name} and let it respond?`
+      : `Someone DM'd your agent on ${originChannelType}. Wire it to ${target.name} and let it respond?`;
+  const options = normalizeOptions(APPROVAL_OPTIONS);
+
+  const inserted = createPendingChannelApproval({
+    messaging_group_id: messagingGroupId,
+    agent_group_id: target.id,
+    original_message: JSON.stringify(event),
+    approver_user_id: delivery.userId,
+    created_at: new Date().toISOString(),
+    title,
+    options_json: JSON.stringify(options),
+  });
+  if (!inserted) {
+    // Lost a concurrent race against another inbound for this same
+    // messaging group. The winner already produced a card; we silently
+    // skip delivery rather than spamming a duplicate. The earlier
+    // `hasInFlightChannelApproval` check catches the common case but
+    // doesn't cover concurrent inbounds that both pass it before either
+    // INSERTs.
+    log.debug('Channel registration card already inserted by concurrent inbound', {
+      messagingGroupId,
+    });
+    return;
+  }
+
+  const adapter = getDeliveryAdapter();
+  if (!adapter) {
+    log.error('Channel registration row created but no delivery adapter is wired', {
+      messagingGroupId,
+    });
+    return;
+  }
+
+  try {
+    await adapter.deliver(
+      delivery.messagingGroup.channel_type,
+      delivery.messagingGroup.platform_id,
+      null,
+      'chat-sdk',
+      JSON.stringify({
+        type: 'ask_question',
+        // Use messaging_group_id as the questionId — it's unique per card
+        // (PK on pending table dedups) and lets the response handler look
+        // up the pending row directly without another index.
+        questionId: messagingGroupId,
+        title,
+        question: appendFallbackNotice(question, delivery.viaFallbackBot, originBotId),
+        options,
+      }),
+    );
+    log.info('Channel registration card delivered', {
+      messagingGroupId,
+      targetAgentGroupId: target.id,
+      approver: delivery.userId,
+    });
+  } catch (err) {
+    log.error('Channel registration card delivery failed', {
+      messagingGroupId,
+      err,
+    });
+  }
+}
+
+export const APPROVE_VALUE = 'approve';
+export const REJECT_VALUE = 'reject';

package/src/modules/permissions/db/agent-group-members.ts

@@ -0,0 +1,44 @@
+import type { AgentGroupMember } from '../../../types.js';
+import { getDb } from '../../../db/connection.js';
+import { isAdminOfAgentGroup, isGlobalAdmin, isOwner } from './user-roles.js';
+
+export function addMember(row: AgentGroupMember): void {
+  getDb()
+    .prepare(
+      `INSERT OR IGNORE INTO agent_group_members (user_id, agent_group_id, added_by, added_at)
+       VALUES (@user_id, @agent_group_id, @added_by, @added_at)`,
+    )
+    .run(row);
+}
+
+export function removeMember(userId: string, agentGroupId: string): void {
+  getDb().prepare('DELETE FROM agent_group_members WHERE user_id = ? AND agent_group_id = ?').run(userId, agentGroupId);
+}
+
+export function getMembers(agentGroupId: string): AgentGroupMember[] {
+  return getDb()
+    .prepare('SELECT * FROM agent_group_members WHERE agent_group_id = ? ORDER BY added_at')
+    .all(agentGroupId) as AgentGroupMember[];
+}
+
+/**
+ * Is the user "known" in this agent group?
+ * Owner, global admin, and scoped admin are implicitly members.
+ */
+export function isMember(userId: string, agentGroupId: string): boolean {
+  if (isOwner(userId) || isGlobalAdmin(userId) || isAdminOfAgentGroup(userId, agentGroupId)) {
+    return true;
+  }
+  const row = getDb()
+    .prepare('SELECT 1 FROM agent_group_members WHERE user_id = ? AND agent_group_id = ? LIMIT 1')
+    .get(userId, agentGroupId);
+  return !!row;
+}
+
+/** Direct row lookup — does not honor the admin/owner implicit-membership rule. */
+export function hasMembershipRow(userId: string, agentGroupId: string): boolean {
+  const row = getDb()
+    .prepare('SELECT 1 FROM agent_group_members WHERE user_id = ? AND agent_group_id = ? LIMIT 1')
+    .get(userId, agentGroupId);
+  return !!row;
+}