@consiliency/agent-board-schema 1.2.0

package/migrations/20260510000000_agent_board_dblint_repairs.sql

@@ -0,0 +1,413 @@
+create or replace function agent_board._next_task_event_sequence(p_task_id uuid)
+returns bigint
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_sequence bigint;
+begin
+  perform 1
+    from agent_board.tasks t
+   where t.id = p_task_id
+   for update;
+
+  select coalesce(max(te.event_sequence), 0) + 1
+    into v_sequence
+    from agent_board.task_events te
+   where te.task_id = p_task_id;
+
+  return v_sequence;
+end;
+$$;
+
+create or replace function agent_board.heartbeat(
+  p_agent_id uuid,
+  p_thread_id uuid default null,
+  p_availability text default 'ready',
+  p_activity_summary text default null,
+  p_expires_in interval default interval '5 minutes',
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(agent_id uuid, availability text, thread_id uuid, last_heartbeat_at timestamptz, expires_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  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_thread_id is not null and not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+
+  return query
+  insert into agent_board.presence as p(agent_id, thread_id, availability, activity_summary, last_heartbeat_at, expires_at, metadata, updated_at)
+  values (p_agent_id, p_thread_id, coalesce(p_availability, 'ready'), p_activity_summary, now(), now() + coalesce(p_expires_in, interval '5 minutes'), coalesce(p_metadata, '{}'::jsonb), now())
+  on conflict on constraint presence_pkey do update
+    set thread_id = excluded.thread_id,
+        availability = excluded.availability,
+        activity_summary = excluded.activity_summary,
+        last_heartbeat_at = excluded.last_heartbeat_at,
+        expires_at = excluded.expires_at,
+        metadata = excluded.metadata,
+        updated_at = excluded.updated_at
+  returning p.agent_id, p.availability, p.thread_id, p.last_heartbeat_at, p.expires_at, p.updated_at;
+end;
+$$;
+
+create or replace function agent_board.mark_read(p_thread_id uuid, p_agent_id uuid, p_last_read_message_sequence bigint)
+returns table(thread_id uuid, agent_id uuid, last_read_message_sequence bigint, last_read_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_sequence bigint;
+begin
+  if p_last_read_message_sequence < 0 then
+    raise exception 'negative read sequence' using errcode = '22023';
+  end if;
+
+  select least(p_last_read_message_sequence, t.last_message_sequence)
+    into v_sequence
+    from agent_board.threads t
+   where t.id = p_thread_id;
+
+  if v_sequence is null then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+
+  return query
+  insert into agent_board.read_receipts as rr(thread_id, agent_id, last_read_message_sequence, last_read_at)
+  values (p_thread_id, p_agent_id, v_sequence, now())
+  on conflict on constraint read_receipts_pkey do update
+    set last_read_message_sequence = greatest(rr.last_read_message_sequence, excluded.last_read_message_sequence),
+        last_read_at = now()
+  returning rr.thread_id, rr.agent_id, rr.last_read_message_sequence, rr.last_read_at;
+end;
+$$;
+
+create or replace function agent_board.resolve_conflict(
+  p_conflict_id uuid,
+  p_resolved_by_agent_id uuid,
+  p_details jsonb default '{}'::jsonb
+)
+returns table(conflict_id uuid, status text, resolved_at timestamptz, updated_at timestamptz, task_event_sequence bigint)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_conflict agent_board.conflicts%rowtype;
+  v_event record;
+begin
+  select *
+    into v_conflict
+    from agent_board.conflicts c
+   where c.id = p_conflict_id
+     and c.status <> 'resolved';
+  if v_conflict.id is null then
+    raise exception 'conflict not found' using errcode = 'P0002';
+  end if;
+
+  update agent_board.conflicts c
+     set status = 'resolved',
+         resolved_by_agent_id = p_resolved_by_agent_id,
+         resolved_at = now(),
+         details = c.details || coalesce(p_details, '{}'::jsonb),
+         updated_at = now()
+   where c.id = p_conflict_id
+   returning * into v_conflict;
+
+  if v_conflict.task_id is not null then
+    select * into v_event
+      from agent_board.append_task_event(v_conflict.task_id, p_resolved_by_agent_id, 'status_changed', jsonb_build_object('kind', 'conflict_resolved', 'conflict_id', p_conflict_id));
+  end if;
+
+  return query
+  select v_conflict.id, v_conflict.status, v_conflict.resolved_at, v_conflict.updated_at, v_event.event_sequence;
+end;
+$$;
+
+create or replace function agent_board.resolve_escalation(
+  p_escalation_id uuid,
+  p_resolved_by_agent_id uuid,
+  p_details jsonb default '{}'::jsonb
+)
+returns table(escalation_id uuid, status text, resolved_at timestamptz, updated_at timestamptz, task_event_sequence bigint)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_escalation agent_board.escalations%rowtype;
+  v_event record;
+begin
+  select *
+    into v_escalation
+    from agent_board.escalations e
+   where e.id = p_escalation_id
+     and e.status <> 'resolved';
+  if v_escalation.id is null then
+    raise exception 'escalation not found' using errcode = 'P0002';
+  end if;
+
+  update agent_board.escalations e
+     set status = 'resolved',
+         resolved_by_agent_id = p_resolved_by_agent_id,
+         resolved_at = now(),
+         details = e.details || coalesce(p_details, '{}'::jsonb),
+         updated_at = now()
+   where e.id = p_escalation_id
+   returning * into v_escalation;
+
+  if v_escalation.task_id is not null then
+    select * into v_event
+      from agent_board.append_task_event(v_escalation.task_id, p_resolved_by_agent_id, 'status_changed', jsonb_build_object('kind', 'escalation_resolved', 'escalation_id', p_escalation_id));
+  end if;
+
+  return query
+  select v_escalation.id, v_escalation.status, v_escalation.resolved_at, v_escalation.updated_at, v_event.event_sequence;
+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 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;
+$$;
+
+revoke all on function agent_board._next_task_event_sequence(uuid) from public, anon, authenticated;
+revoke all on function agent_board.heartbeat(uuid, uuid, text, text, interval, jsonb) from public, anon, authenticated;
+revoke all on function agent_board.mark_read(uuid, uuid, bigint) from public, anon, authenticated;
+revoke all on function agent_board.resolve_conflict(uuid, uuid, jsonb) from public, anon, authenticated;
+revoke all on function agent_board.resolve_escalation(uuid, uuid, jsonb) from public, anon, authenticated;
+revoke all on function agent_board.create_tasking_delivery(uuid, uuid, text, text, uuid[], uuid, text, text, text, jsonb) from public, anon, authenticated;
+
+grant execute on function agent_board._next_task_event_sequence(uuid) to service_role;
+grant execute on function agent_board.heartbeat(uuid, uuid, text, text, interval, jsonb) to service_role;
+grant execute on function agent_board.mark_read(uuid, uuid, bigint) to service_role;
+grant execute on function agent_board.resolve_conflict(uuid, uuid, jsonb) to service_role;
+grant execute on function agent_board.resolve_escalation(uuid, uuid, jsonb) to service_role;
+grant execute on function agent_board.create_tasking_delivery(uuid, uuid, text, text, uuid[], uuid, text, text, text, jsonb) to service_role;

package/migrations/20260511000000_agent_board_auth_schema.sql

@@ -0,0 +1,146 @@
+do $$
+begin
+  if not exists (
+    select 1
+      from pg_type t
+      join pg_namespace n on n.oid = t.typnamespace
+     where n.nspname = 'agent_board'
+       and t.typname = 'agent_kind'
+  ) then
+    create type agent_board.agent_kind as enum ('human', 'agent', 'system');
+  end if;
+end
+$$;
+
+alter table agent_board.agents
+  add column if not exists auth_user_id uuid references auth.users(id) on delete set null,
+  add column if not exists owner_user_id uuid references auth.users(id) on delete set null,
+  add column if not exists kind agent_board.agent_kind;
+
+update agent_board.agents
+   set kind = agent_type::agent_board.agent_kind
+ where kind is null;
+
+create or replace function agent_board.sync_agent_principal_columns()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+begin
+  if new.kind is null
+     or (
+       tg_op = 'UPDATE'
+       and new.kind is not distinct from old.kind
+       and new.agent_type is distinct from old.agent_type
+       and new.agent_type is not null
+     ) then
+    new.kind := new.agent_type::agent_board.agent_kind;
+  end if;
+
+  if new.agent_type is null
+     or (
+       tg_op = 'UPDATE'
+       and new.agent_type is not distinct from old.agent_type
+       and new.kind is distinct from old.kind
+       and new.kind is not null
+     ) then
+    new.agent_type := new.kind::text;
+  end if;
+
+  if new.kind is null or new.agent_type is null then
+    raise exception 'kind and agent_type are both required' using errcode = '23502';
+  end if;
+
+  if new.kind::text <> new.agent_type then
+    raise exception 'kind and agent_type must match' using errcode = '22000';
+  end if;
+
+  if new.kind = 'system'::agent_board.agent_kind then
+    new.owner_user_id := null;
+    new.auth_user_id := null;
+  end if;
+
+  return new;
+end;
+$$;
+
+drop trigger if exists trg_sync_agent_principal_columns on agent_board.agents;
+
+create trigger trg_sync_agent_principal_columns
+before insert or update on agent_board.agents
+for each row execute function agent_board.sync_agent_principal_columns();
+
+do $$
+declare
+  v_provisioning_user_id uuid;
+begin
+  select uor.user_id
+    into v_provisioning_user_id
+    from public.user_org_roles uor
+   where uor.role = 'platform_admin'
+   order by uor.granted_at, uor.user_id
+   limit 1;
+
+  if v_provisioning_user_id is not null then
+    update agent_board.agents
+       set owner_user_id = coalesce(owner_user_id, case when agent_type = 'system' then null else v_provisioning_user_id end),
+           auth_user_id = coalesce(auth_user_id, case when agent_type = 'human' then v_provisioning_user_id else null end),
+           kind = coalesce(kind, agent_type::agent_board.agent_kind),
+           updated_at = now()
+     where agent_type in ('human', 'agent', 'system');
+  end if;
+
+  update agent_board.agents
+     set owner_user_id = null,
+         auth_user_id = null,
+         kind = 'system'::agent_board.agent_kind,
+         updated_at = now()
+   where agent_type = 'system'
+     and (
+       owner_user_id is not null
+       or auth_user_id is not null
+       or kind is distinct from 'system'::agent_board.agent_kind
+     );
+end
+$$;
+
+alter table agent_board.agents
+  drop constraint if exists agents_kind_agent_type_match,
+  add constraint agents_kind_agent_type_match check (kind::text = agent_type),
+  drop constraint if exists agents_system_owner_shape,
+  add constraint agents_system_owner_shape check (
+    (kind = 'system'::agent_board.agent_kind and owner_user_id is null and auth_user_id is null)
+    or kind <> 'system'::agent_board.agent_kind
+  );
+
+create index if not exists idx_agent_board_agents_owner_user_id
+  on agent_board.agents(owner_user_id)
+  where owner_user_id is not null;
+
+create index if not exists idx_agent_board_agents_auth_user_id
+  on agent_board.agents(auth_user_id)
+  where auth_user_id is not null;
+
+create unique index if not exists idx_agent_board_agents_auth_user_id_active_unique
+  on agent_board.agents(auth_user_id)
+  where auth_user_id is not null and status = 'active';
+
+create or replace function agent_board.current_agent_id()
+returns uuid
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select a.id
+    from agent_board.agents a
+   where a.auth_user_id = auth.uid()
+     and a.status = 'active'
+   limit 1;
+$$;
+
+revoke all on function agent_board.current_agent_id() from public, anon, authenticated;
+grant execute on function agent_board.current_agent_id() to authenticated;
+grant execute on function agent_board.current_agent_id() to service_role;
+
+comment on function agent_board.current_agent_id() is 'Resolves auth.uid() to the active agent_board.agents.id or returns null.';

package/migrations/20260511000001_agent_board_auth_credentials.sql

@@ -0,0 +1,39 @@
+create table if not exists agent_board.agent_credentials (
+  id uuid primary key default gen_random_uuid(),
+  agent_id uuid not null references agent_board.agents(id) on delete cascade,
+  refresh_token_hash bytea not null,
+  hash_version integer not null check (hash_version > 0),
+  credential_label text not null,
+  expires_at timestamptz not null,
+  last_used_at timestamptz,
+  revoked_at timestamptz,
+  rotated_at timestamptz,
+  replaced_by_credential_id uuid references agent_board.agent_credentials(id) on delete set null,
+  replaces_credential_id uuid references agent_board.agent_credentials(id) on delete set null,
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint agent_credentials_not_self_replaced_by check (replaced_by_credential_id is null or replaced_by_credential_id <> id),
+  constraint agent_credentials_not_self_replaces check (replaces_credential_id is null or replaces_credential_id <> id),
+  constraint agent_credentials_revocation_rotation_shape check (
+    revoked_at is null
+    or rotated_at is null
+    or revoked_at <= rotated_at
+  )
+);
+
+comment on table agent_board.agent_credentials is 'Durable hashed refresh-token references plus lifecycle metadata for one agent principal.';
+
+create index if not exists idx_agent_board_agent_credentials_agent
+  on agent_board.agent_credentials(agent_id, created_at desc);
+
+create unique index if not exists idx_agent_board_agent_credentials_refresh_token_hash
+  on agent_board.agent_credentials(refresh_token_hash);
+
+create index if not exists idx_agent_board_agent_credentials_active
+  on agent_board.agent_credentials(agent_id, expires_at, created_at desc)
+  where revoked_at is null;
+
+insert into agent_board.schema_version (version)
+values (2)
+on conflict ((true)) do update set version = excluded.version;