@consiliency/agent-board-schema 1.2.0

package/migrations/20260506000000_agent_board_inbox_delivery_rpcs.sql

@@ -0,0 +1,1200 @@
+create or replace function agent_board._trim_inbox_text(p_value text, p_max_length integer)
+returns text
+language sql
+immutable
+as $$
+  select case
+    when p_value is null then null
+    else nullif(left(trim(p_value), p_max_length), '')
+  end
+$$;
+
+create or replace function agent_board._lock_idempotency_key(p_namespace text, p_idempotency_key text)
+returns void
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  if nullif(trim(p_idempotency_key), '') is null then
+    return;
+  end if;
+
+  perform pg_advisory_xact_lock(hashtextextended(p_namespace || ':' || trim(p_idempotency_key), 0));
+end;
+$$;
+
+create or replace function agent_board._build_fetch_descriptor(
+  p_surface text,
+  p_target_id uuid,
+  p_view text,
+  p_reason text,
+  p_filters jsonb default '{}'::jsonb
+)
+returns jsonb
+language sql
+immutable
+as $$
+  select jsonb_build_object(
+    'surface', p_surface,
+    'targetId', p_target_id::text,
+    'view', p_view,
+    'filters', coalesce(p_filters, '{}'::jsonb),
+    'reason', p_reason
+  )
+$$;
+
+create or replace function agent_board._active_board_membership_id(p_board_id uuid, p_agent_id uuid)
+returns uuid
+language sql
+stable
+as $$
+  select bm.id
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+     and bm.membership_state in ('joined', 'subscribed')
+   order by bm.created_at desc
+   limit 1
+$$;
+
+create or replace function agent_board._upsert_delivery_recipient(
+  p_delivery_mode text,
+  p_recipient_agent_id uuid,
+  p_source_kind text,
+  p_source_message_id uuid default null,
+  p_source_task_id uuid default null,
+  p_source_delegation_id uuid default null,
+  p_board_id uuid default null,
+  p_board_membership_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns agent_board.delivery_recipients
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row agent_board.delivery_recipients%rowtype;
+begin
+  insert into agent_board.delivery_recipients(
+    delivery_mode,
+    recipient_agent_id,
+    source_kind,
+    source_message_id,
+    source_task_id,
+    source_delegation_id,
+    board_id,
+    board_membership_id,
+    metadata
+  )
+  values (
+    p_delivery_mode,
+    p_recipient_agent_id,
+    p_source_kind,
+    p_source_message_id,
+    p_source_task_id,
+    p_source_delegation_id,
+    p_board_id,
+    p_board_membership_id,
+    coalesce(p_metadata, '{}'::jsonb)
+  )
+  on conflict (recipient_agent_id, canonical_source_key) do update
+    set metadata = coalesce(agent_board.delivery_recipients.metadata, '{}'::jsonb) || coalesce(excluded.metadata, '{}'::jsonb)
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+create or replace function agent_board._upsert_inbox_item(
+  p_delivery_recipient_id uuid,
+  p_recipient_agent_id uuid,
+  p_board_id uuid,
+  p_delivery_mode text,
+  p_source_kind text,
+  p_source_message_id uuid default null,
+  p_source_task_id uuid default null,
+  p_source_delegation_id uuid default null,
+  p_subject text default null,
+  p_preview text default null,
+  p_priority text default 'medium',
+  p_visible_in_inbox boolean default true,
+  p_visible_in_board_feed boolean default false,
+  p_fetch_descriptor jsonb default '{}'::jsonb,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns agent_board.inbox_items
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row agent_board.inbox_items%rowtype;
+begin
+  insert into agent_board.inbox_items(
+    delivery_recipient_id,
+    recipient_agent_id,
+    board_id,
+    delivery_mode,
+    source_kind,
+    source_message_id,
+    source_task_id,
+    source_delegation_id,
+    subject,
+    preview,
+    priority,
+    visible_in_inbox,
+    visible_in_board_feed,
+    fetch_descriptor,
+    metadata
+  )
+  values (
+    p_delivery_recipient_id,
+    p_recipient_agent_id,
+    p_board_id,
+    p_delivery_mode,
+    p_source_kind,
+    p_source_message_id,
+    p_source_task_id,
+    p_source_delegation_id,
+    p_subject,
+    p_preview,
+    p_priority,
+    p_visible_in_inbox,
+    p_visible_in_board_feed,
+    coalesce(p_fetch_descriptor, '{}'::jsonb),
+    coalesce(p_metadata, '{}'::jsonb)
+  )
+  on conflict (delivery_recipient_id) do update
+    set board_id = excluded.board_id,
+        subject = excluded.subject,
+        preview = excluded.preview,
+        priority = excluded.priority,
+        visible_in_inbox = excluded.visible_in_inbox,
+        visible_in_board_feed = excluded.visible_in_board_feed,
+        fetch_descriptor = excluded.fetch_descriptor,
+        metadata = coalesce(agent_board.inbox_items.metadata, '{}'::jsonb) || coalesce(excluded.metadata, '{}'::jsonb),
+        updated_at = now()
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+create or replace function agent_board._queue_inbox_callbacks(p_inbox_item_id uuid, p_event_category text)
+returns integer
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_inserted_count integer := 0;
+begin
+  if p_event_category not in ('inbox.item.delivered', 'inbox.item.updated') then
+    raise exception 'unsupported inbox callback event category' using errcode = '22023';
+  end if;
+
+  with inserted as (
+    insert into agent_board.callback_outbox_events(
+      endpoint_id,
+      subscription_id,
+      recipient_agent_id,
+      inbox_item_id,
+      board_id,
+      event_category,
+      delivery_mode,
+      source_kind,
+      source_message_id,
+      source_task_id,
+      source_delegation_id,
+      idempotency_key,
+      subject,
+      preview,
+      priority,
+      fetch_descriptor,
+      metadata
+    )
+    select
+      cs.endpoint_id,
+      cs.id,
+      ii.recipient_agent_id,
+      ii.id,
+      null,
+      p_event_category,
+      ii.delivery_mode,
+      ii.source_kind,
+      ii.source_message_id,
+      ii.source_task_id,
+      ii.source_delegation_id,
+      case
+        when p_event_category = 'inbox.item.delivered' then
+          p_event_category || ':' || ii.id::text || ':' || cs.id::text
+        else
+          p_event_category || ':' || ii.id::text || ':' || cs.id::text || ':' || replace(ii.updated_at::text, ' ', 'T') || ':' || ii.action_state
+      end,
+      ii.subject,
+      ii.preview,
+      ii.priority,
+      ii.fetch_descriptor,
+      jsonb_build_object(
+        'subscriptionScope', cs.subscription_scope,
+        'subscriptionStatus', cs.subscription_status,
+        'actionState', ii.action_state
+      )
+    from agent_board.inbox_items ii
+    join agent_board.callback_subscriptions cs
+      on cs.agent_id = ii.recipient_agent_id
+     and cs.subscription_scope = 'own_inbox'
+     and cs.subscription_status = 'active'
+     and cs.event_category = p_event_category
+    join agent_board.callback_endpoints ce
+      on ce.id = cs.endpoint_id
+     and ce.owner_agent_id = cs.agent_id
+     and ce.endpoint_status = 'verified'
+    where ii.id = p_inbox_item_id
+    on conflict (idempotency_key) do nothing
+    returning 1
+  )
+  select count(*) into v_inserted_count from inserted;
+
+  return v_inserted_count;
+end;
+$$;
+
+create or replace function agent_board._queue_board_post_callbacks(
+  p_board_id uuid,
+  p_message_id uuid,
+  p_subject text,
+  p_preview text,
+  p_priority text,
+  p_fetch_descriptor jsonb
+)
+returns integer
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_inserted_count integer := 0;
+begin
+  with inserted as (
+    insert into agent_board.callback_outbox_events(
+      endpoint_id,
+      subscription_id,
+      recipient_agent_id,
+      inbox_item_id,
+      board_id,
+      event_category,
+      delivery_mode,
+      source_kind,
+      source_message_id,
+      idempotency_key,
+      subject,
+      preview,
+      priority,
+      fetch_descriptor,
+      metadata
+    )
+    select
+      cs.endpoint_id,
+      cs.id,
+      cs.agent_id,
+      null,
+      p_board_id,
+      'board.post.delivered',
+      'board',
+      'message',
+      p_message_id,
+      'board.post.delivered:' || p_message_id::text || ':' || cs.id::text,
+      p_subject,
+      p_preview,
+      p_priority,
+      p_fetch_descriptor,
+      jsonb_build_object(
+        'subscriptionScope', cs.subscription_scope,
+        'subscriptionStatus', cs.subscription_status
+      )
+    from agent_board.callback_subscriptions cs
+    join agent_board.callback_endpoints ce
+      on ce.id = cs.endpoint_id
+     and ce.owner_agent_id = cs.agent_id
+     and ce.endpoint_status = 'verified'
+    join agent_board.board_memberships bm
+      on bm.id = cs.board_membership_id
+     and bm.membership_state in ('joined', 'subscribed')
+    where cs.subscription_scope = 'board'
+      and cs.subscription_status = 'active'
+      and cs.event_category = 'board.post.delivered'
+      and cs.board_id = p_board_id
+    on conflict (idempotency_key) do nothing
+    returning 1
+  )
+  select count(*) into v_inserted_count from inserted;
+
+  return v_inserted_count;
+end;
+$$;
+
+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 $$
+begin
+  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;
+  if not exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  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), ''), p_created_by_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;
+begin
+  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;
+  if not exists (select 1 from agent_board.agents where id = p_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+  if p_created_by_agent_id is not null and not exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'creator agent 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 = p_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, p_agent_id, p_membership_state, coalesce(p_created_by_agent_id, p_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;
+begin
+  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 = p_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 $$
+begin
+  return query
+  select *
+    from agent_board.update_board_membership(p_board_id, p_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), '');
+begin
+  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.agents where id = p_author_agent_id) then
+    raise exception 'author agent not found' using errcode = 'P0002';
+  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 || ':' || p_author_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 = p_author_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,
+        p_author_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), '');
+begin
+  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 exists (select 1 from agent_board.agents where id = p_author_agent_id) then
+    raise exception 'author agent not found' using errcode = 'P0002';
+  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 || ':' || p_author_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 = p_author_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,
+        p_author_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), '');
+begin
+  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.agents where id = p_author_agent_id) then
+    raise exception 'author agent 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;
+
+  perform agent_board._lock_idempotency_key(
+    'post_board_message:' || p_thread_id::text || ':' || p_author_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 = p_author_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,
+        p_author_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), '');
+begin
+  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 exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'creator agent not found' using errcode = 'P0002';
+  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 and 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 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 || ':' || p_created_by_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 = p_created_by_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,
+        p_created_by_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 id
+      into v_created_event_id
+      from agent_board.task_events
+     where task_id = v_task.id
+       and 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;
+begin
+  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 = p_recipient_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;
+$$;
+
+revoke all on all functions in schema agent_board from public, anon, authenticated;
+grant execute on all functions in schema agent_board to service_role;