@consiliency/agent-board-schema 1.2.0

package/migrations/20260508000000_agent_board_callback_runtime.sql

@@ -0,0 +1,453 @@
+create or replace function agent_board._next_callback_attempt_number(
+  p_outbox_event_id uuid
+)
+returns integer
+language sql
+security definer
+set search_path = agent_board, public
+stable
+as $$
+  select coalesce(max(cda.attempt_number), 0) + 1
+    from agent_board.callback_delivery_attempts cda
+   where cda.outbox_event_id = p_outbox_event_id;
+$$;
+
+create or replace function agent_board.claim_callback_outbox_events(
+  p_batch_size integer default 25
+)
+returns table(
+  outbox_event_id uuid,
+  endpoint_id uuid,
+  subscription_id uuid,
+  recipient_agent_id uuid,
+  inbox_item_id uuid,
+  board_id uuid,
+  endpoint_url text,
+  signing_key_version integer,
+  event_category text,
+  delivery_mode text,
+  source_kind text,
+  source_message_id uuid,
+  source_task_id uuid,
+  source_delegation_id uuid,
+  idempotency_key text,
+  subject text,
+  preview text,
+  priority text,
+  fetch_descriptor jsonb,
+  outbox_created_at timestamptz,
+  queued_at timestamptz,
+  claimed_at timestamptz,
+  attempt_number integer,
+  endpoint_status text,
+  subscription_status text,
+  metadata jsonb
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  if p_batch_size is null or p_batch_size < 1 or p_batch_size > 100 then
+    raise exception 'callback batch size must be between 1 and 100' using errcode = '22023';
+  end if;
+
+  return query
+  with candidates as (
+    select coe.id
+      from agent_board.callback_outbox_events coe
+      join agent_board.callback_endpoints ce on ce.id = coe.endpoint_id
+      join agent_board.callback_subscriptions cs on cs.id = coe.subscription_id
+     where coe.outbox_status in ('pending', 'retryable')
+       and coe.available_at <= now()
+       and ce.endpoint_status = 'verified'
+       and cs.subscription_status = 'active'
+     order by coe.available_at asc, coe.created_at asc, coe.id asc
+     for update of coe skip locked
+     limit p_batch_size
+  ),
+  updated as (
+    update agent_board.callback_outbox_events coe
+       set outbox_status = 'delivering',
+           locked_at = now(),
+           updated_at = now()
+      from candidates
+     where coe.id = candidates.id
+     returning coe.*
+  )
+  select
+    u.id,
+    u.endpoint_id,
+    u.subscription_id,
+    u.recipient_agent_id,
+    u.inbox_item_id,
+    u.board_id,
+    ce.endpoint_url,
+    ce.signing_key_version,
+    u.event_category,
+    u.delivery_mode,
+    u.source_kind,
+    u.source_message_id,
+    u.source_task_id,
+    u.source_delegation_id,
+    u.idempotency_key,
+    u.subject,
+    u.preview,
+    u.priority,
+    u.fetch_descriptor,
+    u.created_at,
+    u.available_at,
+    u.locked_at,
+    agent_board._next_callback_attempt_number(u.id),
+    ce.endpoint_status,
+    cs.subscription_status,
+    coalesce(u.metadata, '{}'::jsonb)
+  from updated u
+  join agent_board.callback_endpoints ce on ce.id = u.endpoint_id
+  join agent_board.callback_subscriptions cs on cs.id = u.subscription_id;
+end;
+$$;
+
+create or replace function agent_board.record_callback_delivery_success(
+  p_outbox_event_id uuid,
+  p_endpoint_id uuid,
+  p_http_status integer default 200,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  outbox_event_id uuid,
+  endpoint_id uuid,
+  outbox_status text,
+  attempt_outcome text,
+  attempt_number integer,
+  delivered_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_outbox agent_board.callback_outbox_events%rowtype;
+  v_attempt_number integer;
+  v_finished_at timestamptz := now();
+begin
+  select *
+    into v_outbox
+    from agent_board.callback_outbox_events coe
+   where coe.id = p_outbox_event_id
+     and coe.endpoint_id = p_endpoint_id
+   for update;
+
+  if v_outbox.id is null then
+    raise exception 'callback outbox event not found' using errcode = 'P0002';
+  end if;
+
+  v_attempt_number := agent_board._next_callback_attempt_number(v_outbox.id);
+
+  insert into agent_board.callback_delivery_attempts(
+    outbox_event_id,
+    endpoint_id,
+    attempt_number,
+    attempt_outcome,
+    http_status,
+    started_at,
+    finished_at,
+    metadata
+  )
+  values (
+    v_outbox.id,
+    p_endpoint_id,
+    v_attempt_number,
+    'delivered',
+    p_http_status,
+    coalesce(v_outbox.locked_at, v_finished_at),
+    v_finished_at,
+    coalesce(p_metadata, '{}'::jsonb)
+  );
+
+  update agent_board.callback_outbox_events coe
+     set outbox_status = 'delivered',
+         delivered_at = v_finished_at,
+         last_error_at = null,
+         locked_at = null,
+         updated_at = v_finished_at,
+         metadata = coalesce(coe.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb)
+   where coe.id = v_outbox.id;
+
+  update agent_board.callback_endpoints ce
+     set last_delivery_at = v_finished_at,
+         updated_at = v_finished_at
+   where ce.id = p_endpoint_id;
+
+  return query
+  select v_outbox.id, p_endpoint_id, 'delivered'::text, 'delivered'::text, v_attempt_number, v_finished_at;
+end;
+$$;
+
+create or replace function agent_board.record_callback_delivery_retry(
+  p_outbox_event_id uuid,
+  p_endpoint_id uuid,
+  p_http_status integer default null,
+  p_error_summary text default null,
+  p_next_retry_at timestamptz default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  outbox_event_id uuid,
+  endpoint_id uuid,
+  outbox_status text,
+  attempt_outcome text,
+  attempt_number integer,
+  next_retry_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_outbox agent_board.callback_outbox_events%rowtype;
+  v_attempt_number integer;
+  v_finished_at timestamptz := now();
+begin
+  select *
+    into v_outbox
+    from agent_board.callback_outbox_events coe
+   where coe.id = p_outbox_event_id
+     and coe.endpoint_id = p_endpoint_id
+   for update;
+
+  if v_outbox.id is null then
+    raise exception 'callback outbox event not found' using errcode = 'P0002';
+  end if;
+  if p_next_retry_at is null or p_next_retry_at <= v_finished_at then
+    raise exception 'next retry timestamp must be in the future' using errcode = '22023';
+  end if;
+
+  v_attempt_number := agent_board._next_callback_attempt_number(v_outbox.id);
+
+  insert into agent_board.callback_delivery_attempts(
+    outbox_event_id,
+    endpoint_id,
+    attempt_number,
+    attempt_outcome,
+    http_status,
+    error_summary,
+    started_at,
+    finished_at,
+    next_retry_at,
+    metadata
+  )
+  values (
+    v_outbox.id,
+    p_endpoint_id,
+    v_attempt_number,
+    'retryable_failure',
+    p_http_status,
+    nullif(trim(p_error_summary), ''),
+    coalesce(v_outbox.locked_at, v_finished_at),
+    v_finished_at,
+    p_next_retry_at,
+    coalesce(p_metadata, '{}'::jsonb)
+  );
+
+  update agent_board.callback_outbox_events coe
+     set outbox_status = 'retryable',
+         available_at = p_next_retry_at,
+         last_error_at = v_finished_at,
+         locked_at = null,
+         updated_at = v_finished_at,
+         metadata = coalesce(coe.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb)
+   where coe.id = v_outbox.id;
+
+  update agent_board.callback_endpoints ce
+     set last_failure_at = v_finished_at,
+         updated_at = v_finished_at
+   where ce.id = p_endpoint_id;
+
+  return query
+  select v_outbox.id, p_endpoint_id, 'retryable'::text, 'retryable_failure'::text, v_attempt_number, p_next_retry_at;
+end;
+$$;
+
+create or replace function agent_board.record_callback_delivery_terminal_failure(
+  p_outbox_event_id uuid,
+  p_endpoint_id uuid,
+  p_http_status integer default null,
+  p_error_summary text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  outbox_event_id uuid,
+  endpoint_id uuid,
+  outbox_status text,
+  attempt_outcome text,
+  attempt_number integer,
+  failed_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_outbox agent_board.callback_outbox_events%rowtype;
+  v_attempt_number integer;
+  v_finished_at timestamptz := now();
+begin
+  select *
+    into v_outbox
+    from agent_board.callback_outbox_events coe
+   where coe.id = p_outbox_event_id
+     and coe.endpoint_id = p_endpoint_id
+   for update;
+
+  if v_outbox.id is null then
+    raise exception 'callback outbox event not found' using errcode = 'P0002';
+  end if;
+
+  v_attempt_number := agent_board._next_callback_attempt_number(v_outbox.id);
+
+  insert into agent_board.callback_delivery_attempts(
+    outbox_event_id,
+    endpoint_id,
+    attempt_number,
+    attempt_outcome,
+    http_status,
+    error_summary,
+    started_at,
+    finished_at,
+    metadata
+  )
+  values (
+    v_outbox.id,
+    p_endpoint_id,
+    v_attempt_number,
+    'terminal_failure',
+    p_http_status,
+    nullif(trim(p_error_summary), ''),
+    coalesce(v_outbox.locked_at, v_finished_at),
+    v_finished_at,
+    coalesce(p_metadata, '{}'::jsonb)
+  );
+
+  update agent_board.callback_outbox_events coe
+     set outbox_status = 'failed',
+         last_error_at = v_finished_at,
+         locked_at = null,
+         updated_at = v_finished_at,
+         metadata = coalesce(coe.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb)
+   where coe.id = v_outbox.id;
+
+  update agent_board.callback_endpoints ce
+     set last_failure_at = v_finished_at,
+         updated_at = v_finished_at
+   where ce.id = p_endpoint_id;
+
+  return query
+  select v_outbox.id, p_endpoint_id, 'failed'::text, 'terminal_failure'::text, v_attempt_number, v_finished_at;
+end;
+$$;
+
+create or replace function agent_board.disable_callback_delivery_endpoint(
+  p_endpoint_id uuid,
+  p_outbox_event_id uuid default null,
+  p_disabled_reason text default null,
+  p_error_summary text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  endpoint_id uuid,
+  endpoint_status text,
+  outbox_event_id uuid,
+  outbox_status text,
+  attempt_outcome text,
+  disabled_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_endpoint agent_board.callback_endpoints%rowtype;
+  v_outbox agent_board.callback_outbox_events%rowtype;
+  v_attempt_number integer;
+  v_disabled_at timestamptz := now();
+begin
+  select *
+    into v_endpoint
+    from agent_board.callback_endpoints ce
+   where ce.id = p_endpoint_id
+   for update;
+
+  if v_endpoint.id is null then
+    raise exception 'callback endpoint not found' using errcode = 'P0002';
+  end if;
+
+  update agent_board.callback_endpoints ce
+     set endpoint_status = 'disabled',
+         disabled_at = coalesce(ce.disabled_at, v_disabled_at),
+         disabled_reason = coalesce(nullif(trim(p_disabled_reason), ''), ce.disabled_reason, 'callback runtime disabled endpoint'),
+         last_failure_at = v_disabled_at,
+         updated_at = v_disabled_at,
+         metadata = coalesce(ce.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb)
+   where ce.id = p_endpoint_id
+   returning * into v_endpoint;
+
+  update agent_board.callback_subscriptions cs
+     set subscription_status = 'disabled',
+         disabled_at = coalesce(cs.disabled_at, v_disabled_at),
+         updated_at = v_disabled_at
+   where cs.endpoint_id = p_endpoint_id
+     and cs.subscription_status <> 'disabled';
+
+  update agent_board.callback_outbox_events coe
+     set outbox_status = 'disabled',
+         last_error_at = v_disabled_at,
+         locked_at = null,
+         updated_at = v_disabled_at,
+         metadata = coalesce(coe.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb)
+   where coe.endpoint_id = p_endpoint_id
+     and coe.outbox_status in ('pending', 'delivering', 'retryable');
+
+  if p_outbox_event_id is not null then
+    select *
+      into v_outbox
+      from agent_board.callback_outbox_events coe
+     where coe.id = p_outbox_event_id
+       and coe.endpoint_id = p_endpoint_id
+     for update;
+
+    if v_outbox.id is null then
+      raise exception 'callback outbox event not found' using errcode = 'P0002';
+    end if;
+
+    v_attempt_number := agent_board._next_callback_attempt_number(v_outbox.id);
+
+    insert into agent_board.callback_delivery_attempts(
+      outbox_event_id,
+      endpoint_id,
+      attempt_number,
+      attempt_outcome,
+      error_summary,
+      started_at,
+      finished_at,
+      metadata
+    )
+    values (
+      v_outbox.id,
+      p_endpoint_id,
+      v_attempt_number,
+      'endpoint_disabled',
+      coalesce(nullif(trim(p_error_summary), ''), nullif(trim(p_disabled_reason), ''), 'callback endpoint disabled'),
+      coalesce(v_outbox.locked_at, v_disabled_at),
+      v_disabled_at,
+      coalesce(p_metadata, '{}'::jsonb)
+    );
+  end if;
+
+  return query
+  select p_endpoint_id, 'disabled'::text, p_outbox_event_id, 'disabled'::text, 'endpoint_disabled'::text, v_disabled_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;

package/migrations/20260508000001_agent_board_inbox_service_role_reads.sql

@@ -0,0 +1,10 @@
+grant select on agent_board.v_agent_inbox,
+  agent_board.v_agent_inbox_counts,
+  agent_board.v_board_directory,
+  agent_board.v_board_memberships,
+  agent_board.v_board_feed,
+  agent_board.v_callback_endpoint_status,
+  agent_board.v_callback_subscriptions,
+  agent_board.v_callback_delivery_health,
+  agent_board.v_agent_dashboard
+to service_role;