@consiliency/agent-board-schema 1.2.0

package/migrations/20260517000000_agent_board_addressing.sql

@@ -0,0 +1,542 @@
+create or replace function agent_board._addressing_descriptors_array(p_descriptors jsonb)
+returns jsonb
+language sql
+immutable
+set search_path = ''
+as $$
+  select case
+    when p_descriptors is null then '[]'::jsonb
+    when jsonb_typeof(p_descriptors) = 'array' then p_descriptors
+    else jsonb_build_array(p_descriptors)
+  end;
+$$;
+
+create or replace function agent_board._resolve_addressing_recipient_rows(
+  p_actor_agent_id uuid,
+  p_recipient_descriptors jsonb
+)
+returns table(
+  ordinal integer,
+  recipient_agent_id uuid,
+  handle text,
+  display_name text,
+  descriptor jsonb,
+  warning text,
+  denied_reason text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_descriptor jsonb;
+  v_kind text;
+  v_index integer := 0;
+  v_match_count integer;
+  v_group_alias text;
+  v_role text;
+begin
+  for v_descriptor in
+    select value
+      from jsonb_array_elements(agent_board._addressing_descriptors_array(p_recipient_descriptors))
+  loop
+    v_index := v_index + 1;
+    v_kind := v_descriptor ->> 'kind';
+
+    if v_kind = 'explicit_set' then
+      return query
+      select v_index * 100000 + nested.ordinal,
+             nested.recipient_agent_id,
+             nested.handle,
+             nested.display_name,
+             nested.descriptor,
+             nested.warning,
+             nested.denied_reason
+        from agent_board._resolve_addressing_recipient_rows(
+          p_actor_agent_id,
+          coalesce(v_descriptor -> 'recipients', '[]'::jsonb)
+        ) nested;
+    elsif v_kind = 'agent_id' then
+      select count(*) into v_match_count
+        from agent_board.agents a
+       where a.id = (v_descriptor ->> 'agentId')::uuid
+         and a.status = 'active';
+
+      if v_match_count = 1 then
+        return query
+        select v_index, a.id, a.handle, a.display_name, v_descriptor, null::text, null::text
+          from agent_board.agents a
+         where a.id = (v_descriptor ->> 'agentId')::uuid
+           and a.status = 'active';
+      else
+        return query select v_index, null::uuid, null::text, null::text, v_descriptor, null::text, 'unknown agent_id'::text;
+      end if;
+    elsif v_kind in ('agent_handle', 'human_handle') then
+      select count(*) into v_match_count
+        from agent_board.agents a
+       where a.handle = v_descriptor ->> 'handle'
+         and a.status = 'active'
+         and (
+           (v_kind = 'agent_handle' and a.agent_type <> 'human')
+           or (v_kind = 'human_handle' and a.agent_type = 'human')
+         );
+
+      if v_match_count = 1 then
+        return query
+        select v_index, a.id, a.handle, a.display_name, v_descriptor, null::text, null::text
+          from agent_board.agents a
+         where a.handle = v_descriptor ->> 'handle'
+           and a.status = 'active'
+           and (
+             (v_kind = 'agent_handle' and a.agent_type <> 'human')
+             or (v_kind = 'human_handle' and a.agent_type = 'human')
+           );
+      elsif v_match_count = 0 then
+        return query select v_index, null::uuid, null::text, null::text, v_descriptor, null::text, 'unknown handle'::text;
+      else
+        return query select v_index, null::uuid, null::text, null::text, v_descriptor, null::text, 'ambiguous handle'::text;
+      end if;
+    elsif v_kind = 'group_alias' then
+      v_group_alias := nullif(trim(v_descriptor ->> 'groupAlias'), '');
+      return query
+      select v_index,
+             a.id,
+             a.handle,
+             a.display_name,
+             v_descriptor,
+             null::text,
+             null::text
+        from agent_board.agents a
+       where a.status = 'active'
+         and (
+           a.metadata ->> 'groupAlias' = v_group_alias
+           or a.metadata ->> 'group_alias' = v_group_alias
+           or coalesce(a.metadata -> 'groupAliases', '[]'::jsonb) ? v_group_alias
+           or coalesce(a.metadata -> 'group_aliases', '[]'::jsonb) ? v_group_alias
+         )
+       order by a.handle, a.id;
+
+      if not found then
+        return query select v_index, null::uuid, null::text, null::text, v_descriptor, null::text, 'unknown group_alias'::text;
+      end if;
+    elsif v_kind = 'role_selector' then
+      v_role := nullif(trim(v_descriptor ->> 'role'), '');
+      return query
+      select v_index,
+             a.id,
+             a.handle,
+             a.display_name,
+             v_descriptor,
+             null::text,
+             null::text
+        from agent_board.agents a
+       where a.status = 'active'
+         and (
+           a.agent_type = v_role
+           or a.kind::text = v_role
+           or a.metadata ->> 'role' = v_role
+           or coalesce(a.metadata -> 'roles', '[]'::jsonb) ? v_role
+           or coalesce(a.metadata -> 'scopes', '[]'::jsonb) ? v_role
+         )
+       order by a.handle, a.id;
+
+      if not found then
+        return query select v_index, null::uuid, null::text, null::text, v_descriptor, null::text, 'unknown role_selector'::text;
+      end if;
+    else
+      return query select v_index, null::uuid, null::text, null::text, v_descriptor, null::text, 'unsupported descriptor kind'::text;
+    end if;
+  end loop;
+end;
+$$;
+
+create or replace function agent_board.resolve_recipients(
+  p_actor_agent_id uuid default null,
+  p_recipient_descriptors jsonb default '[]'::jsonb
+)
+returns table("resolvedRecipients" jsonb, warnings jsonb, "deniedRecipients" jsonb, "idempotentThreadReuse" boolean)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  return query
+  with resolved as (
+    select *
+      from agent_board._resolve_addressing_recipient_rows(p_actor_agent_id, p_recipient_descriptors)
+  ),
+  accepted as (
+    select distinct on (recipient_agent_id)
+           recipient_agent_id,
+           handle,
+           display_name,
+           descriptor,
+           ordinal
+      from resolved
+     where recipient_agent_id is not null
+     order by recipient_agent_id, ordinal
+  ),
+  ordered_accepted as (
+    select *
+      from accepted
+     order by ordinal, handle, recipient_agent_id
+  ),
+  duplicate_count as (
+    select greatest(count(*) - count(distinct recipient_agent_id), 0) as collapsed
+      from resolved
+     where recipient_agent_id is not null
+  )
+  select coalesce(
+           jsonb_agg(
+             jsonb_build_object(
+               'agentId', ordered_accepted.recipient_agent_id::text,
+               'handle', ordered_accepted.handle,
+               'displayName', ordered_accepted.display_name,
+               'descriptor', ordered_accepted.descriptor
+             )
+             order by ordered_accepted.ordinal, ordered_accepted.handle, ordered_accepted.recipient_agent_id
+           ) filter (where ordered_accepted.recipient_agent_id is not null),
+           '[]'::jsonb
+         ) as "resolvedRecipients",
+         case
+           when (select collapsed from duplicate_count) > 0
+             then jsonb_build_array((select collapsed::text || ' duplicate recipient(s) collapsed' from duplicate_count))
+           else '[]'::jsonb
+         end as warnings,
+         coalesce(
+           jsonb_agg(
+             jsonb_build_object('descriptor', denied.descriptor, 'reason', denied.denied_reason)
+             order by denied.ordinal
+           ) filter (where denied.denied_reason is not null),
+           '[]'::jsonb
+         ) as "deniedRecipients",
+         false as "idempotentThreadReuse"
+    from ordered_accepted
+    full join resolved denied on false;
+end;
+$$;
+
+create or replace function agent_board.expand_recipients_dry_run(
+  p_actor_agent_id uuid default null,
+  p_recipient_descriptors jsonb default '[]'::jsonb,
+  p_thread_idempotency_key text default null
+)
+returns table("resolvedRecipients" jsonb, warnings jsonb, "deniedRecipients" jsonb, "idempotentThreadReuse" boolean)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  return query
+  select r."resolvedRecipients",
+         r.warnings,
+         r."deniedRecipients",
+         exists (
+           select 1
+             from agent_board.threads t
+            where t.created_by_agent_id = coalesce(p_actor_agent_id, agent_board.current_agent_id())
+              and t.metadata ->> 'addressingThreadKey' = nullif(trim(p_thread_idempotency_key), '')
+         ) as "idempotentThreadReuse"
+    from agent_board.resolve_recipients(p_actor_agent_id, p_recipient_descriptors) r;
+end;
+$$;
+
+create or replace function agent_board.create_or_find_thread(
+  p_created_by_agent_id uuid,
+  p_subject text,
+  p_idempotency_key text,
+  p_thread_type text default 'coordination',
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(thread_id uuid, thread_type text, subject text, status text, last_message_sequence bigint, created_at timestamptz, updated_at timestamptz, reused boolean)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_agent_id uuid;
+  v_key text := nullif(trim(p_idempotency_key), '');
+  v_thread agent_board.threads%rowtype;
+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_subject), '') is null or v_key is null then
+    raise exception 'subject and idempotency key are required' using errcode = '22023';
+  end if;
+
+  select *
+    into v_thread
+    from agent_board.threads t
+   where t.created_by_agent_id = v_actor_agent_id
+     and t.metadata ->> 'addressingThreadKey' = v_key
+   order by t.created_at desc
+   limit 1
+   for update;
+
+  if v_thread.id is not null then
+    return query select v_thread.id, v_thread.thread_type, v_thread.subject, v_thread.status, v_thread.last_message_sequence, v_thread.created_at, v_thread.updated_at, true;
+    return;
+  end if;
+
+  insert into agent_board.threads(thread_type, created_by_agent_id, subject, metadata)
+  values (
+    coalesce(nullif(trim(p_thread_type), ''), 'coordination'),
+    v_actor_agent_id,
+    trim(p_subject),
+    coalesce(p_metadata, '{}'::jsonb) || jsonb_build_object('addressingThreadKey', v_key)
+  )
+  returning * into v_thread;
+
+  return query select v_thread.id, v_thread.thread_type, v_thread.subject, v_thread.status, v_thread.last_message_sequence, v_thread.created_at, v_thread.updated_at, false;
+end;
+$$;
+
+create or replace function agent_board._addressing_agent_ids_or_raise(
+  p_actor_agent_id uuid,
+  p_recipient_descriptors jsonb
+)
+returns uuid[]
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_result record;
+  v_ids uuid[];
+begin
+  select * into v_result
+    from agent_board.resolve_recipients(p_actor_agent_id, p_recipient_descriptors);
+
+  if jsonb_array_length(v_result."deniedRecipients") > 0 then
+    raise exception 'recipient descriptor resolution failed' using errcode = '22023', detail = v_result."deniedRecipients"::text;
+  end if;
+
+  select array_agg((value ->> 'agentId')::uuid)
+    into v_ids
+    from jsonb_array_elements(v_result."resolvedRecipients") as value;
+
+  if v_ids is null or cardinality(v_ids) = 0 then
+    raise exception 'recipient descriptors resolved no recipients' using errcode = '22023';
+  end if;
+
+  return v_ids;
+end;
+$$;
+
+drop function if exists agent_board.send_direct_message(uuid, uuid, jsonb, text, text, text, text, text, jsonb);
+drop function if exists agent_board.send_direct_message(uuid, uuid, jsonb, text, text, text, text, text, text, jsonb);
+
+create or replace function agent_board.send_direct_message(
+  p_thread_id uuid,
+  p_author_agent_id uuid,
+  p_recipient_descriptor jsonb,
+  p_addressing_mode text,
+  p_subject text,
+  p_body text,
+  p_message_type text,
+  p_priority text,
+  p_idempotency_key text,
+  p_metadata 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_recipients uuid[];
+begin
+  if p_addressing_mode <> 'addressing_v1' then
+    raise exception 'invalid addressing mode' using errcode = '22023';
+  end if;
+  v_recipients := agent_board._addressing_agent_ids_or_raise(p_author_agent_id, jsonb_build_array(p_recipient_descriptor));
+  if cardinality(v_recipients) <> 1 then
+    raise exception 'direct message requires exactly one recipient' using errcode = '22023';
+  end if;
+
+  return query
+  select *
+    from agent_board.send_direct_message(
+      p_thread_id,
+      p_author_agent_id,
+      v_recipients[1],
+      p_subject,
+      p_body,
+      p_message_type,
+      p_priority,
+      p_idempotency_key,
+      p_metadata
+    );
+end;
+$$;
+
+drop function if exists agent_board.send_multicast_message(uuid, uuid, jsonb, text, text, text, text, text, jsonb);
+drop function if exists agent_board.send_multicast_message(uuid, uuid, jsonb, text, text, text, text, text, text, jsonb);
+
+create or replace function agent_board.send_multicast_message(
+  p_thread_id uuid,
+  p_author_agent_id uuid,
+  p_recipient_descriptors jsonb,
+  p_addressing_mode text,
+  p_subject text,
+  p_body text,
+  p_message_type text,
+  p_priority text,
+  p_idempotency_key text,
+  p_metadata 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 $$
+begin
+  if p_addressing_mode <> 'addressing_v1' then
+    raise exception 'invalid addressing mode' using errcode = '22023';
+  end if;
+
+  return query
+  select *
+    from agent_board.send_multicast_message(
+      p_thread_id,
+      p_author_agent_id,
+      agent_board._addressing_agent_ids_or_raise(p_author_agent_id, p_recipient_descriptors),
+      p_subject,
+      p_body,
+      p_message_type,
+      p_priority,
+      p_idempotency_key,
+      p_metadata
+    );
+end;
+$$;
+
+drop function if exists agent_board.post_board_message(uuid, uuid, text, text, text, text, text, text, jsonb);
+drop function if exists agent_board.post_board_message(uuid, uuid, text, text, text, text, text, text, text, jsonb);
+
+create or replace function agent_board.post_board_message(
+  p_thread_id uuid,
+  p_author_agent_id uuid,
+  p_board_slug text,
+  p_addressing_mode text,
+  p_subject text,
+  p_body text,
+  p_message_type text,
+  p_priority text,
+  p_idempotency_key text,
+  p_metadata 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_board_id uuid;
+begin
+  if p_addressing_mode <> 'addressing_v1' then
+    raise exception 'invalid addressing mode' using errcode = '22023';
+  end if;
+
+  select b.id into v_board_id
+    from agent_board.boards b
+   where b.slug = nullif(trim(p_board_slug), '')
+     and b.status = 'active';
+  if v_board_id is null then
+    raise exception 'board slug not found' using errcode = 'P0002';
+  end if;
+
+  return query
+  select *
+    from agent_board.post_board_message(
+      p_thread_id,
+      p_author_agent_id,
+      v_board_id,
+      p_subject,
+      p_body,
+      p_message_type,
+      p_priority,
+      p_idempotency_key,
+      p_metadata
+    );
+end;
+$$;
+
+drop function if exists agent_board.create_tasking_delivery(uuid, uuid, text, text, jsonb, text, text, text, text, jsonb);
+drop function if exists agent_board.create_tasking_delivery(uuid, uuid, text, text, jsonb, text, text, text, text, text, jsonb);
+
+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,
+  p_recipient_descriptors jsonb,
+  p_board_slug text,
+  p_addressing_mode text,
+  p_priority text,
+  p_orchestration_mode text,
+  p_idempotency_key text,
+  p_metadata 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_recipient_ids uuid[];
+  v_board_id uuid;
+begin
+  if p_addressing_mode <> 'addressing_v1' then
+    raise exception 'invalid addressing mode' using errcode = '22023';
+  end if;
+
+  if p_recipient_descriptors is not null then
+    v_recipient_ids := agent_board._addressing_agent_ids_or_raise(p_created_by_agent_id, p_recipient_descriptors);
+  end if;
+  if nullif(trim(p_board_slug), '') is not null then
+    select b.id into v_board_id
+      from agent_board.boards b
+     where b.slug = trim(p_board_slug)
+       and b.status = 'active';
+    if v_board_id is null then
+      raise exception 'board slug not found' using errcode = 'P0002';
+    end if;
+  end if;
+
+  return query
+  select result.task_id,
+         result.created_event_id,
+         result.delivered_recipient_count,
+         result.inbox_item_count,
+         result.callback_outbox_count,
+         result.created_at,
+         result.updated_at
+    from agent_board.create_tasking_delivery(
+      p_thread_id,
+      p_created_by_agent_id,
+      p_title,
+      p_details,
+      v_recipient_ids,
+      v_board_id,
+      p_priority,
+      p_orchestration_mode,
+      p_idempotency_key,
+      p_metadata
+    ) result;
+end;
+$$;
+
+revoke all on function agent_board.resolve_recipients(uuid, jsonb) from public, anon;
+revoke all on function agent_board.expand_recipients_dry_run(uuid, jsonb, text) from public, anon;
+revoke all on function agent_board.create_or_find_thread(uuid, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.send_direct_message(uuid, uuid, jsonb, text, text, text, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.send_multicast_message(uuid, uuid, jsonb, text, text, text, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.post_board_message(uuid, uuid, text, text, text, text, text, text, text, jsonb) from public, anon;
+revoke all on function agent_board.create_tasking_delivery(uuid, uuid, text, text, jsonb, text, text, text, text, text, jsonb) from public, anon;
+grant execute on function agent_board.resolve_recipients(uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.expand_recipients_dry_run(uuid, jsonb, text) to authenticated, service_role;
+grant execute on function agent_board.create_or_find_thread(uuid, text, text, text, jsonb) to authenticated, service_role;
+grant execute on function agent_board.send_direct_message(uuid, uuid, jsonb, text, text, text, text, text, text, jsonb) to authenticated, service_role;
+grant execute on function agent_board.send_multicast_message(uuid, uuid, jsonb, text, text, text, text, text, text, jsonb) to authenticated, service_role;
+grant execute on function agent_board.post_board_message(uuid, uuid, text, text, text, text, text, text, text, jsonb) to authenticated, service_role;
+grant execute on function agent_board.create_tasking_delivery(uuid, uuid, text, text, jsonb, text, text, text, text, text, jsonb) to authenticated, service_role;