@consiliency/agent-board-schema 1.2.0

package/migrations/20260515000000_agent_board_boardopt.sql

@@ -0,0 +1,493 @@
+alter table agent_board.boards
+  add column if not exists visibility text not null default 'private';
+
+alter table agent_board.boards
+  drop constraint if exists boards_visibility_check;
+
+alter table agent_board.boards
+  add constraint boards_visibility_check
+  check (visibility in ('private', 'invite_only', 'open', 'directory_hidden'));
+
+alter table agent_board.board_memberships
+  drop constraint if exists board_memberships_membership_state_check;
+
+alter table agent_board.board_memberships
+  add constraint board_memberships_membership_state_check
+  check (membership_state in ('requested', 'invited', 'joined', 'subscribed', 'left', 'removed'));
+
+alter table agent_board.board_memberships
+  drop constraint if exists board_memberships_state_left_at;
+
+alter table agent_board.board_memberships
+  add constraint board_memberships_state_left_at check (
+    (membership_state in ('requested', 'invited', 'joined', 'subscribed') and left_at is null)
+    or (membership_state in ('left', 'removed') and left_at is not null)
+  );
+
+create index if not exists idx_agent_board_boards_visibility
+  on agent_board.boards(visibility, status, name, id);
+
+create index if not exists idx_agent_board_board_memberships_agent_state
+  on agent_board.board_memberships(agent_id, membership_state, updated_at desc);
+
+drop function if exists agent_board.create_board(uuid, text, text, text, jsonb);
+
+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,
+  p_visibility text default 'private'
+)
+returns table(board_id uuid, slug text, name text, status text, visibility 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 coalesce(p_visibility, 'private') not in ('private', 'invite_only', 'open', 'directory_hidden') then
+    raise exception 'invalid board visibility' 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, visibility, metadata)
+  values (
+    trim(p_slug),
+    trim(p_name),
+    nullif(trim(p_description), ''),
+    p_created_by_agent_id,
+    coalesce(p_visibility, 'private'),
+    coalesce(p_metadata, '{}'::jsonb)
+  )
+  on conflict on constraint boards_slug_key do update
+    set name = excluded.name,
+        description = excluded.description,
+        status = 'active',
+        visibility = excluded.visibility,
+        metadata = coalesce(b.metadata, '{}'::jsonb) || coalesce(excluded.metadata, '{}'::jsonb),
+        updated_at = now()
+  returning b.id, b.slug, b.name, b.status, b.visibility, b.created_at, b.updated_at;
+end;
+$$;
+
+create or replace function agent_board._upsert_board_membership_state(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns agent_board.board_memberships
+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 ('requested', 'invited', '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
+    insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, left_at, metadata)
+    values (
+      p_board_id,
+      p_agent_id,
+      p_membership_state,
+      p_created_by_agent_id,
+      case when p_membership_state in ('left', 'removed') then now() else null end,
+      coalesce(p_metadata, '{}'::jsonb)
+    )
+    returning * into v_membership;
+  else
+    update agent_board.board_memberships bm
+       set membership_state = p_membership_state,
+           created_by_agent_id = coalesce(p_created_by_agent_id, bm.created_by_agent_id),
+           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;
+  end if;
+
+  return v_membership;
+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_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+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.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_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  select bm.membership_state
+    into v_existing_state
+    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;
+
+  if v_actor is not null and v_actor <> p_agent_id and v_actor <> v_board.created_by_agent_id then
+    raise exception 'board membership actor mismatch' using errcode = '42501';
+  end if;
+
+  if v_actor is not null
+     and v_actor = p_agent_id
+     and v_board.created_by_agent_id <> v_actor
+     and not (
+       v_board.visibility = 'open'
+       or (v_board.visibility = 'invite_only' and v_existing_state = 'invited')
+       or v_existing_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'board is not joinable by this agent' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    coalesce(p_created_by_agent_id, p_agent_id),
+    p_metadata
+  );
+
+  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 not exists (
+    select 1
+      from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+       and bm.agent_id = p_agent_id
+  ) then
+    raise exception 'board membership not found' using errcode = 'P0002';
+  end if;
+
+  select * into v_membership
+    from agent_board._upsert_board_membership_state(
+      p_board_id,
+      p_agent_id,
+      p_membership_state,
+      null,
+      p_metadata
+    );
+
+  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.request_join_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, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  select * into v_board
+    from agent_board.boards
+   where id = p_board_id
+     and status = 'active'
+     and visibility in ('open', 'invite_only');
+
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null and v_actor <> p_agent_id then
+    raise exception 'board request actor mismatch' using errcode = '42501';
+  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;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    'requested',
+    p_agent_id,
+    p_metadata
+  );
+
+  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.invite_board_member(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_created_by_agent_id uuid,
+  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_board agent_board.boards%rowtype;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null
+     and v_actor <> v_board.created_by_agent_id
+     and not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'board invite requires active membership' using errcode = '42501';
+  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 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;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    'invited',
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  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.resolve_board_request(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_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_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if p_membership_state not in ('joined', 'subscribed', 'removed') then
+    raise exception 'resolve_board_request only accepts joined, subscribed, or removed' using errcode = '22023';
+  end if;
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null
+     and v_actor <> v_board.created_by_agent_id
+     and not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'board request resolution requires active membership' using errcode = '42501';
+  end if;
+
+  select bm.membership_state
+    into v_existing_state
+    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;
+
+  if v_existing_state not in ('requested', 'invited') then
+    raise exception 'pending board membership not found' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  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;
+$$;
+
+drop view if exists agent_board.v_board_directory;
+
+create view agent_board.v_board_directory
+with (security_invoker = true)
+as
+select
+  b.id as board_id,
+  b.slug as board_slug,
+  b.name as board_name,
+  b.description as board_description,
+  b.status as board_status,
+  b.visibility as board_visibility,
+  b.created_by_agent_id,
+  creator.handle as created_by_handle,
+  coalesce(members.active_member_count, 0)::bigint as active_member_count,
+  current_membership.membership_state as current_membership_state,
+  coalesce(board_activity.latest_board_activity_at, b.updated_at) as latest_board_activity_at,
+  b.created_at,
+  b.updated_at
+from agent_board.boards b
+join agent_board.agents creator on creator.id = b.created_by_agent_id
+left join lateral (
+  select count(*) as active_member_count
+    from agent_board.board_memberships bm
+   where bm.board_id = b.id
+     and bm.membership_state in ('joined', 'subscribed')
+) members on true
+left join lateral (
+  select bm.membership_state
+    from agent_board.board_memberships bm
+   where bm.board_id = b.id
+     and bm.agent_id = agent_board.current_agent_id()
+   order by bm.created_at desc
+   limit 1
+) current_membership on true
+left join lateral (
+  select max(ii.created_at) as latest_board_activity_at
+    from agent_board.inbox_items ii
+   where ii.board_id = b.id
+     and ii.visible_in_board_feed = true
+) board_activity on true
+where b.status = 'active'
+  and b.visibility <> 'directory_hidden'
+  and (
+    b.visibility = 'open'
+    or b.created_by_agent_id = agent_board.current_agent_id()
+    or current_membership.membership_state is not null
+  );
+
+drop policy if exists agent_board_authenticated_select_boards on agent_board.boards;
+create policy agent_board_authenticated_select_boards
+on agent_board.boards
+as permissive
+for select
+to authenticated
+using (
+  created_by_agent_id = agent_board.current_agent_id()
+  or (visibility = 'open' and status = 'active')
+  or exists (
+    select 1
+      from agent_board.board_memberships bm
+     where bm.board_id = boards.id
+       and bm.agent_id = agent_board.current_agent_id()
+       and bm.membership_state in ('requested', 'invited', 'joined', 'subscribed')
+  )
+);
+
+drop policy if exists agent_board_authenticated_select_board_memberships on agent_board.board_memberships;
+create policy agent_board_authenticated_select_board_memberships
+on agent_board.board_memberships
+as permissive
+for select
+to authenticated
+using (
+  agent_id = agent_board.current_agent_id()
+);
+
+revoke all on function agent_board.create_board(uuid, text, text, text, jsonb, text) from public, anon;
+revoke all on function agent_board._upsert_board_membership_state(uuid, uuid, text, uuid, jsonb) from public, anon, authenticated;
+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.request_join_board(uuid, uuid, jsonb) from public, anon;
+revoke all on function agent_board.invite_board_member(uuid, uuid, uuid, jsonb) from public, anon;
+revoke all on function agent_board.resolve_board_request(uuid, uuid, text, uuid, jsonb) from public, anon;
+
+grant select on agent_board.v_board_directory to authenticated, service_role;
+
+grant execute on function agent_board.create_board(uuid, text, text, text, jsonb, text) to authenticated, service_role;
+grant execute on function agent_board.join_board(uuid, uuid, text, uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.update_board_membership(uuid, uuid, text, jsonb) to authenticated, service_role;
+grant execute on function agent_board.request_join_board(uuid, uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.invite_board_member(uuid, uuid, uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.resolve_board_request(uuid, uuid, text, uuid, jsonb) to authenticated, service_role;
+
+insert into agent_board.schema_version (version)
+values (4)
+on conflict ((true)) do update set version = excluded.version;

package/migrations/20260516000000_agent_board_callbackcap.sql

@@ -0,0 +1,113 @@
+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;
+  v_metadata jsonb;
+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;
+
+  v_metadata := coalesce(p_metadata, '{}'::jsonb)
+    || jsonb_build_object(
+      'verificationMethod',
+      'administrative_enablement',
+      'controlProofRequired',
+      true
+    );
+
+  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,
+    v_metadata
+  )
+  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) || excluded.metadata,
+        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;
+  v_control_proof_ref text := nullif(trim(coalesce(p_metadata ->> 'controlProofRef', '')), '');
+  v_metadata jsonb;
+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);
+
+  if v_control_proof_ref is null then
+    raise exception 'callback endpoint verification requires controlProofRef metadata' using errcode = '22023';
+  end if;
+
+  v_metadata := coalesce(v_endpoint.metadata, '{}'::jsonb)
+    || coalesce(p_metadata, '{}'::jsonb)
+    || jsonb_build_object(
+      'verificationMethod',
+      'administrative_enablement',
+      'controlProofRef',
+      v_control_proof_ref,
+      'controlProofRecordedAt',
+      now()
+    );
+
+  update agent_board.callback_endpoints ce
+     set endpoint_status = 'verified',
+         verified_at = now(),
+         disabled_at = null,
+         disabled_reason = null,
+         metadata = v_metadata,
+         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;
+$$;
+
+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 all functions in schema agent_board to service_role;