@consiliency/agent-board-schema 1.2.0

package/migrations/20260512000002_agent_board_auth_v2_rpcs.sql

@@ -0,0 +1,1243 @@
+create or replace function agent_board.create_board(
+  p_created_by_agent_id uuid,
+  p_slug text,
+  p_name text,
+  p_description text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(board_id uuid, slug text, name text, status text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  if nullif(trim(p_slug), '') is null or nullif(trim(p_name), '') is null then
+    raise exception 'board slug and name are required' using errcode = '22023';
+  end if;
+
+  return query
+  insert into agent_board.boards as b(slug, name, description, created_by_agent_id, metadata)
+  values (trim(p_slug), trim(p_name), nullif(trim(p_description), ''), v_actor_agent_id, coalesce(p_metadata, '{}'::jsonb))
+  on conflict on constraint boards_slug_key do update
+    set name = excluded.name,
+        description = excluded.description,
+        status = 'active',
+        metadata = coalesce(b.metadata, '{}'::jsonb) || coalesce(excluded.metadata, '{}'::jsonb),
+        updated_at = now()
+  returning b.id, b.slug, b.name, b.status, b.created_at, b.updated_at;
+end;
+$$;
+
+create or replace function agent_board.join_board(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text default 'joined',
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor_agent_id uuid;
+  v_created_by_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+  if p_created_by_agent_id is null then
+    v_created_by_agent_id := case when agent_board._is_service_role() then null else v_actor_agent_id end;
+  else
+    v_created_by_agent_id := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+  end if;
+
+  if p_membership_state not in ('joined', 'subscribed') then
+    raise exception 'join_board only accepts joined or subscribed' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.boards where id = p_board_id) then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  select *
+    into v_membership
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = v_actor_agent_id
+   order by bm.created_at desc
+   limit 1
+   for update;
+
+  if v_membership.id is null then
+    insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, metadata)
+    values (p_board_id, v_actor_agent_id, p_membership_state, coalesce(v_created_by_agent_id, v_actor_agent_id), coalesce(p_metadata, '{}'::jsonb))
+    returning * into v_membership;
+  else
+    update agent_board.board_memberships bm
+       set membership_state = p_membership_state,
+           left_at = null,
+           metadata = coalesce(bm.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+           updated_at = now()
+     where bm.id = v_membership.id
+     returning * into v_membership;
+  end if;
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.created_at, v_membership.updated_at;
+end;
+$$;
+
+create or replace function agent_board.update_board_membership(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, left_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+
+  if p_membership_state not in ('joined', 'subscribed', 'left', 'removed') then
+    raise exception 'invalid board membership state' using errcode = '22023';
+  end if;
+
+  select *
+    into v_membership
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = v_actor_agent_id
+   order by bm.created_at desc
+   limit 1
+   for update;
+
+  if v_membership.id is null then
+    raise exception 'board membership not found' using errcode = 'P0002';
+  end if;
+
+  update agent_board.board_memberships bm
+     set membership_state = p_membership_state,
+         left_at = case when p_membership_state in ('left', 'removed') then now() else null end,
+         metadata = coalesce(bm.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+         updated_at = now()
+   where bm.id = v_membership.id
+   returning * into v_membership;
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.left_at, v_membership.updated_at;
+end;
+$$;
+
+create or replace function agent_board.leave_board(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, left_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+
+  return query
+  select *
+    from agent_board.update_board_membership(p_board_id, v_actor_agent_id, 'left', p_metadata);
+end;
+$$;
+
+create or replace function agent_board.send_direct_message(
+  p_thread_id uuid,
+  p_author_agent_id uuid,
+  p_recipient_agent_id uuid,
+  p_subject text,
+  p_body text,
+  p_message_type text default 'comment',
+  p_priority text default 'medium',
+  p_idempotency_key text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(message_id uuid, delivery_recipient_id uuid, inbox_item_id uuid, callback_outbox_count integer, created_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_message agent_board.messages%rowtype;
+  v_created_message record;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_subject), '') is null or nullif(trim(p_body), '') is null then
+    raise exception 'subject and body are required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_recipient_agent_id) then
+    raise exception 'recipient agent not found' using errcode = 'P0002';
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'send_direct_message:' || p_thread_id::text || ':' || v_actor_agent_id::text,
+    v_idempotency_key
+  );
+
+  if v_idempotency_key is not null then
+    select *
+      into v_message
+      from agent_board.messages
+     where thread_id = p_thread_id
+       and author_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'send_direct_message'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc
+     limit 1;
+  end if;
+
+  if v_message.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'send_direct_message',
+        'subject', trim(p_subject),
+        'priority', p_priority
+      );
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_message
+      from agent_board.post_message(
+        p_thread_id,
+        v_actor_agent_id,
+        p_body,
+        p_message_type,
+        null,
+        v_metadata
+      );
+
+    select *
+      into v_message
+      from agent_board.messages
+     where id = v_created_message.message_id;
+  end if;
+
+  v_preview := agent_board._trim_inbox_text(p_body, 280);
+  v_fetch_descriptor := agent_board._build_fetch_descriptor(
+    'thread',
+    p_thread_id,
+    'agent_board.v_thread_feed',
+    'direct delivery',
+    jsonb_build_object('messageId', v_message.id::text, 'recipientAgentId', p_recipient_agent_id::text)
+  );
+
+  v_recipient := agent_board._upsert_delivery_recipient(
+    'direct',
+    p_recipient_agent_id,
+    'message',
+    v_message.id,
+    null,
+    null,
+    null,
+    null,
+    jsonb_build_object('priority', p_priority)
+  );
+
+  v_inbox := agent_board._upsert_inbox_item(
+    v_recipient.id,
+    p_recipient_agent_id,
+    null,
+    v_recipient.delivery_mode,
+    'message',
+    v_message.id,
+    null,
+    null,
+    trim(p_subject),
+    v_preview,
+    p_priority,
+    true,
+    false,
+    v_fetch_descriptor,
+    jsonb_build_object('threadId', p_thread_id::text)
+  );
+
+  v_callback_count := agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+
+  return query
+  select v_message.id, v_recipient.id, v_inbox.id, v_callback_count, v_message.created_at;
+end;
+$$;
+
+create or replace function agent_board.send_multicast_message(
+  p_thread_id uuid,
+  p_author_agent_id uuid,
+  p_recipient_agent_ids uuid[],
+  p_subject text,
+  p_body text,
+  p_message_type text default 'comment',
+  p_priority text default 'medium',
+  p_idempotency_key text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(message_id uuid, delivered_recipient_count integer, inbox_item_count integer, callback_outbox_count integer, created_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_message agent_board.messages%rowtype;
+  v_created_message record;
+  v_recipient_ids uuid[];
+  v_recipient_id uuid;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_delivered_count integer := 0;
+  v_inbox_count integer := 0;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_subject), '') is null or nullif(trim(p_body), '') is null then
+    raise exception 'subject and body are required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if p_recipient_agent_ids is null or cardinality(p_recipient_agent_ids) = 0 then
+    raise exception 'recipient_agent_ids must not be empty' using errcode = '22023';
+  end if;
+  if array_position(p_recipient_agent_ids, null) is not null then
+    raise exception 'recipient_agent_ids must not contain nulls' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+
+  select array_agg(distinct recipient_id)
+    into v_recipient_ids
+    from unnest(p_recipient_agent_ids) as recipient_id;
+
+  if (
+    select count(*)
+      from agent_board.agents
+     where id = any(v_recipient_ids)
+  ) <> cardinality(v_recipient_ids) then
+    raise exception 'recipient agent not found' using errcode = 'P0002';
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'send_multicast_message:' || p_thread_id::text || ':' || v_actor_agent_id::text,
+    v_idempotency_key
+  );
+
+  if v_idempotency_key is not null then
+    select *
+      into v_message
+      from agent_board.messages
+     where thread_id = p_thread_id
+       and author_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'send_multicast_message'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc
+     limit 1;
+  end if;
+
+  if v_message.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'send_multicast_message',
+        'subject', trim(p_subject),
+        'priority', p_priority
+      );
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_message
+      from agent_board.post_message(
+        p_thread_id,
+        v_actor_agent_id,
+        p_body,
+        p_message_type,
+        null,
+        v_metadata
+      );
+
+    select *
+      into v_message
+      from agent_board.messages
+     where id = v_created_message.message_id;
+  end if;
+
+  v_preview := agent_board._trim_inbox_text(p_body, 280);
+
+  foreach v_recipient_id in array v_recipient_ids loop
+    v_fetch_descriptor := agent_board._build_fetch_descriptor(
+      'thread',
+      p_thread_id,
+      'agent_board.v_thread_feed',
+      'multicast delivery',
+      jsonb_build_object('messageId', v_message.id::text, 'recipientAgentId', v_recipient_id::text)
+    );
+
+    v_recipient := agent_board._upsert_delivery_recipient(
+      'multicast',
+      v_recipient_id,
+      'message',
+      v_message.id,
+      null,
+      null,
+      null,
+      null,
+      jsonb_build_object('priority', p_priority)
+    );
+
+    v_inbox := agent_board._upsert_inbox_item(
+      v_recipient.id,
+      v_recipient_id,
+      null,
+      v_recipient.delivery_mode,
+      'message',
+      v_message.id,
+      null,
+      null,
+      trim(p_subject),
+      v_preview,
+      p_priority,
+      true,
+      false,
+      v_fetch_descriptor,
+      jsonb_build_object('threadId', p_thread_id::text)
+    );
+
+    v_delivered_count := v_delivered_count + 1;
+    v_inbox_count := v_inbox_count + 1;
+    v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+  end loop;
+
+  return query
+  select v_message.id, v_delivered_count, v_inbox_count, v_callback_count, v_message.created_at;
+end;
+$$;
+
+create or replace function agent_board.post_board_message(
+  p_thread_id uuid,
+  p_author_agent_id uuid,
+  p_board_id uuid,
+  p_subject text,
+  p_body text,
+  p_message_type text default 'comment',
+  p_priority text default 'medium',
+  p_idempotency_key text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(message_id uuid, board_id uuid, delivered_recipient_count integer, callback_outbox_count integer, created_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_message agent_board.messages%rowtype;
+  v_created_message record;
+  v_membership record;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_delivered_count integer := 0;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_subject), '') is null or nullif(trim(p_body), '') is null then
+    raise exception 'subject and body are required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not exists (select 1 from agent_board.boards where id = p_board_id) then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if not agent_board._current_agent_has_board_access(p_board_id) then
+    raise exception 'board not accessible to current agent' using errcode = '42501';
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'post_board_message:' || p_thread_id::text || ':' || v_actor_agent_id::text || ':' || p_board_id::text,
+    v_idempotency_key
+  );
+
+  if v_idempotency_key is not null then
+    select *
+      into v_message
+      from agent_board.messages
+     where thread_id = p_thread_id
+       and author_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'post_board_message'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc
+     limit 1;
+  end if;
+
+  if v_message.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'post_board_message',
+        'subject', trim(p_subject),
+        'priority', p_priority,
+        'boardId', p_board_id::text
+      );
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_message
+      from agent_board.post_message(
+        p_thread_id,
+        v_actor_agent_id,
+        p_body,
+        p_message_type,
+        null,
+        v_metadata
+      );
+
+    select *
+      into v_message
+      from agent_board.messages
+     where id = v_created_message.message_id;
+  end if;
+
+  v_preview := agent_board._trim_inbox_text(p_body, 280);
+  v_fetch_descriptor := agent_board._build_fetch_descriptor(
+    'board',
+    p_board_id,
+    'agent_board.v_board_feed',
+    'board delivery',
+    jsonb_build_object('messageId', v_message.id::text)
+  );
+
+  for v_membership in
+    select bm.id, bm.agent_id
+      from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+       and bm.membership_state in ('joined', 'subscribed')
+     order by bm.created_at
+  loop
+    v_recipient := agent_board._upsert_delivery_recipient(
+      'board',
+      v_membership.agent_id,
+      'message',
+      v_message.id,
+      null,
+      null,
+      p_board_id,
+      v_membership.id,
+      jsonb_build_object('priority', p_priority)
+    );
+
+    v_inbox := agent_board._upsert_inbox_item(
+      v_recipient.id,
+      v_membership.agent_id,
+      p_board_id,
+      v_recipient.delivery_mode,
+      'message',
+      v_message.id,
+      null,
+      null,
+      trim(p_subject),
+      v_preview,
+      p_priority,
+      true,
+      true,
+      v_fetch_descriptor,
+      jsonb_build_object('threadId', p_thread_id::text, 'boardId', p_board_id::text)
+    );
+
+    v_delivered_count := v_delivered_count + 1;
+    v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+  end loop;
+
+  v_callback_count := v_callback_count + agent_board._queue_board_post_callbacks(
+    p_board_id,
+    v_message.id,
+    trim(p_subject),
+    v_preview,
+    p_priority,
+    v_fetch_descriptor
+  );
+
+  return query
+  select v_message.id, p_board_id, v_delivered_count, v_callback_count, v_message.created_at;
+end;
+$$;
+
+create or replace function agent_board.create_tasking_delivery(
+  p_thread_id uuid,
+  p_created_by_agent_id uuid,
+  p_title text,
+  p_details text default null,
+  p_recipient_agent_ids uuid[] default null,
+  p_board_id uuid default null,
+  p_priority text default 'medium',
+  p_orchestration_mode text default 'distributed',
+  p_idempotency_key text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(task_id uuid, created_event_id uuid, delivered_recipient_count integer, inbox_item_count integer, callback_outbox_count integer, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_task agent_board.tasks%rowtype;
+  v_created_event_id uuid;
+  v_created_task record;
+  v_recipient_ids uuid[];
+  v_recipient_id uuid;
+  v_membership record;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_delivered_count integer := 0;
+  v_inbox_count integer := 0;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  if nullif(trim(p_title), '') is null then
+    raise exception 'task title is required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if p_orchestration_mode not in ('distributed', 'hierarchical', 'hybrid') then
+    raise exception 'invalid orchestration mode' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if (p_recipient_agent_ids is null or cardinality(p_recipient_agent_ids) = 0) and p_board_id is null then
+    raise exception 'tasking delivery requires explicit recipients or a board target' using errcode = '22023';
+  end if;
+  if p_recipient_agent_ids is not null and array_position(p_recipient_agent_ids, null) is not null then
+    raise exception 'recipient_agent_ids must not contain nulls' using errcode = '22023';
+  end if;
+  if p_board_id is not null then
+    if not exists (select 1 from agent_board.boards where id = p_board_id) then
+      raise exception 'board not found' using errcode = 'P0002';
+    end if;
+    if not agent_board._current_agent_has_board_access(p_board_id) then
+      raise exception 'board not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  select array_agg(distinct recipient_id)
+    into v_recipient_ids
+    from unnest(coalesce(p_recipient_agent_ids, '{}'::uuid[])) as recipient_id;
+
+  if v_recipient_ids is not null and (
+    select count(*)
+      from agent_board.agents
+     where id = any(v_recipient_ids)
+  ) <> cardinality(v_recipient_ids) then
+    raise exception 'recipient agent not found' using errcode = 'P0002';
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'create_tasking_delivery:' || p_thread_id::text || ':' || v_actor_agent_id::text,
+    v_idempotency_key
+  );
+
+  if v_idempotency_key is not null then
+    select *
+      into v_task
+      from agent_board.tasks
+     where thread_id = p_thread_id
+       and created_by_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'create_tasking_delivery'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc
+     limit 1;
+  end if;
+
+  if v_task.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'create_tasking_delivery',
+        'priority', p_priority
+      );
+    if p_board_id is not null then
+      v_metadata := v_metadata || jsonb_build_object('boardId', p_board_id::text);
+    end if;
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_task
+      from agent_board.create_task(
+        p_thread_id,
+        v_actor_agent_id,
+        trim(p_title),
+        p_details,
+        null,
+        null,
+        p_priority,
+        p_orchestration_mode,
+        v_metadata
+      );
+
+    v_created_event_id := v_created_task.created_event_id;
+
+    select *
+      into v_task
+      from agent_board.tasks
+     where id = v_created_task.task_id;
+  else
+    select te.id
+      into v_created_event_id
+      from agent_board.task_events te
+     where te.task_id = v_task.id
+       and te.event_sequence = 1;
+  end if;
+
+  v_preview := agent_board._trim_inbox_text(coalesce(p_details, p_title), 280);
+  v_fetch_descriptor := agent_board._build_fetch_descriptor(
+    'task',
+    v_task.id,
+    'agent_board.v_task_tree',
+    'tasking delivery',
+    jsonb_build_object('threadId', p_thread_id::text)
+  );
+
+  if v_recipient_ids is not null then
+    foreach v_recipient_id in array v_recipient_ids loop
+      v_recipient := agent_board._upsert_delivery_recipient(
+        'tasking',
+        v_recipient_id,
+        'task',
+        null,
+        v_task.id,
+        null,
+        null,
+        null,
+        jsonb_build_object('priority', p_priority)
+      );
+
+      v_inbox := agent_board._upsert_inbox_item(
+        v_recipient.id,
+        v_recipient_id,
+        null,
+        v_recipient.delivery_mode,
+        'task',
+        null,
+        v_task.id,
+        null,
+        trim(p_title),
+        v_preview,
+        p_priority,
+        true,
+        false,
+        v_fetch_descriptor,
+        jsonb_build_object('threadId', p_thread_id::text)
+      );
+
+      v_delivered_count := v_delivered_count + 1;
+      v_inbox_count := v_inbox_count + 1;
+      v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+    end loop;
+  end if;
+
+  if p_board_id is not null then
+    for v_membership in
+      select bm.id, bm.agent_id
+        from agent_board.board_memberships bm
+       where bm.board_id = p_board_id
+         and bm.membership_state in ('joined', 'subscribed')
+       order by bm.created_at
+    loop
+      v_recipient := agent_board._upsert_delivery_recipient(
+        'tasking',
+        v_membership.agent_id,
+        'task',
+        null,
+        v_task.id,
+        null,
+        p_board_id,
+        v_membership.id,
+        jsonb_build_object('priority', p_priority)
+      );
+
+      v_inbox := agent_board._upsert_inbox_item(
+        v_recipient.id,
+        v_membership.agent_id,
+        v_recipient.board_id,
+        v_recipient.delivery_mode,
+        'task',
+        null,
+        v_task.id,
+        null,
+        trim(p_title),
+        v_preview,
+        p_priority,
+        true,
+        v_recipient.board_id is not null,
+        v_fetch_descriptor,
+        jsonb_build_object('threadId', p_thread_id::text, 'boardId', p_board_id::text)
+      );
+
+      v_delivered_count := v_delivered_count + 1;
+      v_inbox_count := v_inbox_count + 1;
+      v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+    end loop;
+  end if;
+
+  return query
+  select v_task.id, v_created_event_id, v_delivered_count, v_inbox_count, v_callback_count, v_task.created_at, v_task.updated_at;
+end;
+$$;
+
+create or replace function agent_board.update_inbox_item_state(
+  p_inbox_item_id uuid,
+  p_recipient_agent_id uuid,
+  p_action_state text,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(inbox_item_id uuid, recipient_agent_id uuid, action_state text, callback_outbox_count integer, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_inbox agent_board.inbox_items%rowtype;
+  v_callback_count integer := 0;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_recipient_agent_id, 'p_recipient_agent_id');
+
+  if p_action_state not in ('new', 'read', 'acknowledged', 'deferred', 'dismissed', 'restored') then
+    raise exception 'invalid inbox action state' using errcode = '22023';
+  end if;
+
+  update agent_board.inbox_items ii
+     set action_state = p_action_state,
+         metadata = coalesce(ii.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+         updated_at = now()
+   where ii.id = p_inbox_item_id
+     and ii.recipient_agent_id = v_actor_agent_id
+   returning * into v_inbox;
+
+  if v_inbox.id is null then
+    raise exception 'inbox item not found' using errcode = 'P0002';
+  end if;
+
+  v_callback_count := agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.updated');
+
+  return query
+  select v_inbox.id, v_inbox.recipient_agent_id, v_inbox.action_state, v_callback_count, v_inbox.updated_at;
+end;
+$$;
+
+create or replace function agent_board.register_callback_endpoint(
+  p_owner_agent_id uuid,
+  p_endpoint_url text,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(endpoint_id uuid, owner_agent_id uuid, endpoint_status text, signing_key_version integer, verification_requested_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_owner_agent_id, 'p_owner_agent_id');
+
+  if nullif(trim(p_endpoint_url), '') is null or trim(p_endpoint_url) !~ '^https://.+$' then
+    raise exception 'callback endpoint URL must be https' using errcode = '22023';
+  end if;
+
+  return query
+  insert into agent_board.callback_endpoints as ce(
+    owner_agent_id,
+    endpoint_url,
+    endpoint_status,
+    verification_requested_at,
+    verified_at,
+    disabled_at,
+    disabled_reason,
+    metadata
+  )
+  values (
+    v_actor_agent_id,
+    trim(p_endpoint_url),
+    'pending_verification',
+    now(),
+    null,
+    null,
+    null,
+    coalesce(p_metadata, '{}'::jsonb)
+  )
+  on conflict on constraint callback_endpoints_url_unique do update
+    set endpoint_status = 'pending_verification',
+        verification_requested_at = now(),
+        verified_at = null,
+        disabled_at = null,
+        disabled_reason = null,
+        metadata = coalesce(ce.metadata, '{}'::jsonb) || coalesce(excluded.metadata, '{}'::jsonb),
+        updated_at = now()
+  returning ce.id, ce.owner_agent_id, ce.endpoint_status, ce.signing_key_version, ce.verification_requested_at, ce.updated_at;
+end;
+$$;
+
+create or replace function agent_board.verify_callback_endpoint(
+  p_endpoint_id uuid,
+  p_owner_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(endpoint_id uuid, owner_agent_id uuid, endpoint_status text, verified_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_endpoint agent_board.callback_endpoints%rowtype;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_owner_agent_id, 'p_owner_agent_id');
+  v_endpoint := agent_board._owned_callback_endpoint(p_endpoint_id, v_actor_agent_id);
+
+  update agent_board.callback_endpoints ce
+     set endpoint_status = 'verified',
+         verified_at = now(),
+         disabled_at = null,
+         disabled_reason = null,
+         metadata = coalesce(ce.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+         updated_at = now()
+   where ce.id = v_endpoint.id
+   returning * into v_endpoint;
+
+  return query
+  select v_endpoint.id, v_endpoint.owner_agent_id, v_endpoint.endpoint_status, v_endpoint.verified_at, v_endpoint.updated_at;
+end;
+$$;
+
+create or replace function agent_board.disable_callback_endpoint(
+  p_endpoint_id uuid,
+  p_owner_agent_id uuid,
+  p_disabled_reason text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(endpoint_id uuid, owner_agent_id uuid, endpoint_status text, disabled_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_endpoint agent_board.callback_endpoints%rowtype;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_owner_agent_id, 'p_owner_agent_id');
+  v_endpoint := agent_board._owned_callback_endpoint(p_endpoint_id, v_actor_agent_id);
+
+  update agent_board.callback_endpoints ce
+     set endpoint_status = 'disabled',
+         disabled_at = now(),
+         disabled_reason = nullif(trim(p_disabled_reason), ''),
+         metadata = coalesce(ce.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+         updated_at = now()
+   where ce.id = v_endpoint.id
+   returning * into v_endpoint;
+
+  update agent_board.callback_subscriptions cs
+     set subscription_status = 'disabled',
+         disabled_at = now(),
+         updated_at = now()
+   where cs.endpoint_id = v_endpoint.id
+     and cs.subscription_status = 'active';
+
+  return query
+  select v_endpoint.id, v_endpoint.owner_agent_id, v_endpoint.endpoint_status, v_endpoint.disabled_at, v_endpoint.updated_at;
+end;
+$$;
+
+create or replace function agent_board.rotate_callback_signing_key(
+  p_endpoint_id uuid,
+  p_owner_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(endpoint_id uuid, owner_agent_id uuid, signing_key_version integer, endpoint_status text, verification_requested_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_endpoint agent_board.callback_endpoints%rowtype;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_owner_agent_id, 'p_owner_agent_id');
+  v_endpoint := agent_board._owned_callback_endpoint(p_endpoint_id, v_actor_agent_id);
+
+  update agent_board.callback_endpoints ce
+     set signing_key_version = ce.signing_key_version + 1,
+         endpoint_status = 'pending_verification',
+         verification_requested_at = now(),
+         verified_at = null,
+         disabled_at = null,
+         disabled_reason = null,
+         metadata = coalesce(ce.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+         updated_at = now()
+   where ce.id = v_endpoint.id
+   returning * into v_endpoint;
+
+  return query
+  select v_endpoint.id, v_endpoint.owner_agent_id, v_endpoint.signing_key_version, v_endpoint.endpoint_status, v_endpoint.verification_requested_at, v_endpoint.updated_at;
+end;
+$$;
+
+create or replace function agent_board.delete_callback_endpoint(
+  p_endpoint_id uuid,
+  p_owner_agent_id uuid
+)
+returns table(endpoint_id uuid, owner_agent_id uuid, deleted boolean)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_endpoint_id uuid;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_owner_agent_id, 'p_owner_agent_id');
+
+  delete from agent_board.callback_endpoints ce
+   where ce.id = p_endpoint_id
+     and ce.owner_agent_id = v_actor_agent_id
+   returning id into v_endpoint_id;
+
+  if v_endpoint_id is null then
+    raise exception 'callback endpoint not found' using errcode = 'P0002';
+  end if;
+
+  return query
+  select v_endpoint_id, v_actor_agent_id, true;
+end;
+$$;
+
+create or replace function agent_board.subscribe_callback_endpoint(
+  p_endpoint_id uuid,
+  p_agent_id uuid,
+  p_subscription_scope text,
+  p_event_category text,
+  p_board_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(subscription_id uuid, endpoint_id uuid, agent_id uuid, subscription_scope text, event_category text, board_id uuid, subscription_status text, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_endpoint agent_board.callback_endpoints%rowtype;
+  v_subscription agent_board.callback_subscriptions%rowtype;
+  v_board_membership_id uuid;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+  v_endpoint := agent_board._owned_callback_endpoint(p_endpoint_id, v_actor_agent_id);
+
+  if p_subscription_scope = 'own_inbox' then
+    if p_event_category not in ('inbox.item.delivered', 'inbox.item.updated') or p_board_id is not null then
+      raise exception 'invalid own_inbox subscription shape' using errcode = '22023';
+    end if;
+  elsif p_subscription_scope = 'board' then
+    if p_event_category not in ('board.post.delivered', 'board.post.updated') or p_board_id is null then
+      raise exception 'invalid board subscription shape' using errcode = '22023';
+    end if;
+    v_board_membership_id := agent_board._active_board_membership_id(p_board_id, v_actor_agent_id);
+    if v_board_membership_id is null then
+      raise exception 'board membership not found' using errcode = 'P0002';
+    end if;
+  else
+    raise exception 'invalid subscription scope' using errcode = '22023';
+  end if;
+
+  select *
+    into v_subscription
+    from agent_board.callback_subscriptions cs
+   where cs.endpoint_id = p_endpoint_id
+     and cs.agent_id = v_actor_agent_id
+     and cs.subscription_scope = p_subscription_scope
+     and cs.event_category = p_event_category
+     and coalesce(cs.board_id, '00000000-0000-0000-0000-000000000000'::uuid) = coalesce(p_board_id, '00000000-0000-0000-0000-000000000000'::uuid)
+   order by cs.created_at desc
+   limit 1
+   for update;
+
+  if v_subscription.id is null then
+    insert into agent_board.callback_subscriptions(
+      endpoint_id,
+      agent_id,
+      subscription_scope,
+      event_category,
+      board_id,
+      board_membership_id,
+      metadata
+    )
+    values (
+      v_endpoint.id,
+      v_actor_agent_id,
+      p_subscription_scope,
+      p_event_category,
+      p_board_id,
+      v_board_membership_id,
+      coalesce(p_metadata, '{}'::jsonb)
+    )
+    returning * into v_subscription;
+  else
+    update agent_board.callback_subscriptions
+       set subscription_status = 'active',
+           disabled_at = null,
+           board_membership_id = v_board_membership_id,
+           metadata = coalesce(callback_subscriptions.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+           updated_at = now()
+     where id = v_subscription.id
+     returning * into v_subscription;
+  end if;
+
+  return query
+  select v_subscription.id, v_subscription.endpoint_id, v_subscription.agent_id, v_subscription.subscription_scope, v_subscription.event_category, v_subscription.board_id, v_subscription.subscription_status, v_subscription.updated_at;
+end;
+$$;
+
+create or replace function agent_board.unsubscribe_callback_endpoint(
+  p_endpoint_id uuid,
+  p_agent_id uuid,
+  p_subscription_scope text,
+  p_event_category text,
+  p_board_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(subscription_id uuid, endpoint_id uuid, agent_id uuid, subscription_scope text, event_category text, board_id uuid, subscription_status text, disabled_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_endpoint agent_board.callback_endpoints%rowtype;
+  v_subscription agent_board.callback_subscriptions%rowtype;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+  v_endpoint := agent_board._owned_callback_endpoint(p_endpoint_id, v_actor_agent_id);
+
+  update agent_board.callback_subscriptions cs
+     set subscription_status = 'disabled',
+         disabled_at = now(),
+         metadata = coalesce(cs.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+         updated_at = now()
+   where cs.endpoint_id = v_endpoint.id
+     and cs.agent_id = v_actor_agent_id
+     and cs.subscription_scope = p_subscription_scope
+     and cs.event_category = p_event_category
+     and coalesce(cs.board_id, '00000000-0000-0000-0000-000000000000'::uuid) = coalesce(p_board_id, '00000000-0000-0000-0000-000000000000'::uuid)
+     and cs.subscription_status = 'active'
+   returning * into v_subscription;
+
+  if v_subscription.id is null then
+    raise exception 'callback subscription not found' using errcode = 'P0002';
+  end if;
+
+  return query
+  select v_subscription.id, v_subscription.endpoint_id, v_subscription.agent_id, v_subscription.subscription_scope, v_subscription.event_category, v_subscription.board_id, v_subscription.subscription_status, v_subscription.disabled_at, v_subscription.updated_at;
+end;
+$$;
+
+revoke all on function agent_board.create_board(uuid, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.join_board(uuid, uuid, text, uuid, jsonb) from public, anon;
+revoke all on function agent_board.update_board_membership(uuid, uuid, text, jsonb) from public, anon;
+revoke all on function agent_board.leave_board(uuid, uuid, jsonb) from public, anon;
+revoke all on function agent_board.send_direct_message(uuid, uuid, uuid, text, text, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.send_multicast_message(uuid, uuid, uuid[], text, text, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.post_board_message(uuid, uuid, uuid, text, text, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.create_tasking_delivery(uuid, uuid, text, text, uuid[], uuid, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.update_inbox_item_state(uuid, uuid, text, jsonb) from public, anon;
+revoke all on function agent_board.register_callback_endpoint(uuid, text, jsonb) from public, anon;
+revoke all on function agent_board.verify_callback_endpoint(uuid, uuid, jsonb) from public, anon;
+revoke all on function agent_board.disable_callback_endpoint(uuid, uuid, text, jsonb) from public, anon;
+revoke all on function agent_board.rotate_callback_signing_key(uuid, uuid, jsonb) from public, anon;
+revoke all on function agent_board.delete_callback_endpoint(uuid, uuid) from public, anon;
+revoke all on function agent_board.subscribe_callback_endpoint(uuid, uuid, text, text, uuid, jsonb) from public, anon;
+revoke all on function agent_board.unsubscribe_callback_endpoint(uuid, uuid, text, text, uuid, jsonb) from public, anon;
+
+grant execute on all functions in schema agent_board to service_role;
+grant execute on function agent_board.create_board(uuid, text, text, text, jsonb) to authenticated;
+grant execute on function agent_board.join_board(uuid, uuid, text, uuid, jsonb) to authenticated;
+grant execute on function agent_board.update_board_membership(uuid, uuid, text, jsonb) to authenticated;
+grant execute on function agent_board.leave_board(uuid, uuid, jsonb) to authenticated;
+grant execute on function agent_board.send_direct_message(uuid, uuid, uuid, text, text, text, text, text, jsonb) to authenticated;
+grant execute on function agent_board.send_multicast_message(uuid, uuid, uuid[], text, text, text, text, text, jsonb) to authenticated;
+grant execute on function agent_board.post_board_message(uuid, uuid, uuid, text, text, text, text, text, jsonb) to authenticated;
+grant execute on function agent_board.create_tasking_delivery(uuid, uuid, text, text, uuid[], uuid, text, text, text, jsonb) to authenticated;
+grant execute on function agent_board.update_inbox_item_state(uuid, uuid, text, jsonb) to authenticated;
+grant execute on function agent_board.register_callback_endpoint(uuid, text, jsonb) to authenticated;
+grant execute on function agent_board.verify_callback_endpoint(uuid, uuid, jsonb) to authenticated;
+grant execute on function agent_board.disable_callback_endpoint(uuid, uuid, text, jsonb) to authenticated;
+grant execute on function agent_board.rotate_callback_signing_key(uuid, uuid, jsonb) to authenticated;
+grant execute on function agent_board.delete_callback_endpoint(uuid, uuid) to authenticated;
+grant execute on function agent_board.subscribe_callback_endpoint(uuid, uuid, text, text, uuid, jsonb) to authenticated;
+grant execute on function agent_board.unsubscribe_callback_endpoint(uuid, uuid, text, text, uuid, jsonb) to authenticated;