@consiliency/agent-board-schema 1.2.0

package/migrations/20260503000000_agent_board_rpcs.sql

@@ -0,0 +1,422 @@
+create or replace function agent_board._next_thread_message_sequence(p_thread_id uuid)
+returns bigint
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_sequence bigint;
+begin
+  update agent_board.threads
+     set last_message_sequence = last_message_sequence + 1,
+         updated_at = now()
+   where id = p_thread_id
+   returning last_message_sequence into v_sequence;
+
+  if v_sequence is null then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+
+  return v_sequence;
+end;
+$$;
+
+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
+  select coalesce(max(event_sequence), 0) + 1
+    into v_sequence
+    from agent_board.task_events
+   where task_id = p_task_id
+   for update;
+
+  return v_sequence;
+end;
+$$;
+
+create or replace function agent_board.register_agent(
+  p_agent_type text,
+  p_handle text,
+  p_display_name text,
+  p_status text default 'active',
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(agent_id uuid, handle 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_handle), '') is null or nullif(trim(p_display_name), '') is null then
+    raise exception 'handle and display name are required' using errcode = '22023';
+  end if;
+
+  return query
+  insert into agent_board.agents as a(agent_type, handle, display_name, status, metadata)
+  values (p_agent_type, p_handle, p_display_name, coalesce(p_status, 'active'), coalesce(p_metadata, '{}'::jsonb))
+  on conflict on constraint agents_handle_key do update
+    set agent_type = excluded.agent_type,
+        display_name = excluded.display_name,
+        status = excluded.status,
+        metadata = excluded.metadata,
+        updated_at = now()
+  returning a.id, a.handle, a.status, a.created_at, a.updated_at;
+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(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 (agent_id) 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 presence.agent_id, presence.availability, presence.thread_id, presence.last_heartbeat_at, presence.expires_at, presence.updated_at;
+end;
+$$;
+
+create or replace function agent_board.create_thread(
+  p_created_by_agent_id uuid,
+  p_subject 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)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  if nullif(trim(p_subject), '') is null then
+    raise exception 'subject is 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.threads(created_by_agent_id, subject, thread_type, metadata)
+  values (p_created_by_agent_id, p_subject, coalesce(p_thread_type, 'coordination'), coalesce(p_metadata, '{}'::jsonb))
+  returning id, threads.thread_type, threads.subject, threads.status, threads.last_message_sequence, threads.created_at, threads.updated_at;
+end;
+$$;
+
+create or replace function agent_board.post_message(
+  p_thread_id uuid,
+  p_author_agent_id uuid,
+  p_body text,
+  p_message_type text default 'comment',
+  p_task_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(message_id uuid, thread_id uuid, task_id uuid, message_sequence bigint, created_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_sequence bigint;
+begin
+  if nullif(trim(p_body), '') is null then
+    raise exception 'message body is required' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_author_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+  if p_task_id is not null and not exists (select 1 from agent_board.tasks where id = p_task_id and tasks.thread_id = p_thread_id) then
+    raise exception 'task not found in thread' using errcode = '22023';
+  end if;
+
+  v_sequence := agent_board._next_thread_message_sequence(p_thread_id);
+
+  return query
+  insert into agent_board.messages(thread_id, author_agent_id, task_id, message_sequence, message_type, body, metadata)
+  values (p_thread_id, p_author_agent_id, p_task_id, v_sequence, coalesce(p_message_type, 'comment'), p_body, coalesce(p_metadata, '{}'::jsonb))
+  returning id, messages.thread_id, messages.task_id, messages.message_sequence, messages.created_at;
+end;
+$$;
+
+create or replace function agent_board.create_task(
+  p_thread_id uuid,
+  p_created_by_agent_id uuid,
+  p_title text,
+  p_details text default null,
+  p_assigned_agent_id uuid default null,
+  p_parent_task_id uuid default null,
+  p_priority text default 'medium',
+  p_orchestration_mode text default 'distributed',
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(task_id uuid, parent_task_id uuid, root_task_id uuid, created_event_id uuid, created_event_sequence bigint, status text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_task_id uuid;
+  v_root_task_id uuid;
+  v_event_id uuid;
+begin
+  if nullif(trim(p_title), '') is null then
+    raise exception 'task title is required' 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 'agent not found' using errcode = 'P0002';
+  end if;
+  if p_assigned_agent_id is not null and not exists (select 1 from agent_board.agents where id = p_assigned_agent_id) then
+    raise exception 'assigned agent not found' using errcode = 'P0002';
+  end if;
+
+  if p_parent_task_id is not null then
+    select coalesce(tasks.root_task_id, tasks.id)
+      into v_root_task_id
+      from agent_board.tasks
+     where id = p_parent_task_id and tasks.thread_id = p_thread_id;
+    if v_root_task_id is null then
+      raise exception 'parent task not found in thread' using errcode = '22023';
+    end if;
+  end if;
+
+  v_task_id := gen_random_uuid();
+  if p_parent_task_id is null then
+    v_root_task_id := v_task_id;
+  end if;
+
+  insert into agent_board.tasks(id, thread_id, created_by_agent_id, assigned_agent_id, parent_task_id, root_task_id, title, details, priority, orchestration_mode, metadata)
+  values (v_task_id, p_thread_id, p_created_by_agent_id, p_assigned_agent_id, p_parent_task_id, v_root_task_id, p_title, p_details, coalesce(p_priority, 'medium'), coalesce(p_orchestration_mode, 'distributed'), coalesce(p_metadata, '{}'::jsonb));
+
+  insert into agent_board.task_events(task_id, thread_id, actor_agent_id, event_sequence, event_type, payload)
+  values (v_task_id, p_thread_id, p_created_by_agent_id, 1, 'created', jsonb_build_object('title', p_title))
+  returning id into v_event_id;
+
+  return query
+  select t.id, t.parent_task_id, t.root_task_id, v_event_id, 1::bigint, t.status, t.created_at, t.updated_at
+    from agent_board.tasks t
+   where t.id = v_task_id;
+end;
+$$;
+
+create or replace function agent_board.append_task_event(
+  p_task_id uuid,
+  p_actor_agent_id uuid,
+  p_event_type text,
+  p_payload jsonb default '{}'::jsonb,
+  p_status text default null,
+  p_assigned_agent_id uuid default null,
+  p_completed_at timestamptz default null
+)
+returns table(task_id uuid, thread_id uuid, event_id uuid, event_sequence bigint, task_status text, assigned_agent_id uuid, updated_at timestamptz, completed_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_thread_id uuid;
+  v_sequence bigint;
+  v_event_id uuid;
+begin
+  select tasks.thread_id into v_thread_id from agent_board.tasks where id = p_task_id for update;
+  if v_thread_id is null then
+    raise exception 'task not found' using errcode = 'P0002';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_actor_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+
+  select coalesce(max(te.event_sequence), 0) + 1 into v_sequence from agent_board.task_events te where te.task_id = p_task_id;
+  insert into agent_board.task_events(task_id, thread_id, actor_agent_id, event_sequence, event_type, payload)
+  values (p_task_id, v_thread_id, p_actor_agent_id, v_sequence, p_event_type, coalesce(p_payload, '{}'::jsonb))
+  returning id into v_event_id;
+
+  update agent_board.tasks
+     set status = coalesce(p_status, tasks.status),
+         assigned_agent_id = coalesce(p_assigned_agent_id, tasks.assigned_agent_id),
+         completed_at = coalesce(p_completed_at, tasks.completed_at),
+         updated_at = now()
+   where id = p_task_id;
+
+  return query
+  select t.id, t.thread_id, v_event_id, v_sequence, t.status, t.assigned_agent_id, t.updated_at, t.completed_at
+    from agent_board.tasks t
+   where t.id = p_task_id;
+end;
+$$;
+
+create or replace function agent_board.acquire_claim(
+  p_agent_id uuid,
+  p_resource_kind text,
+  p_resource_key text,
+  p_lease_expires_at timestamptz,
+  p_task_id uuid default null,
+  p_thread_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(claim_id uuid, task_id uuid, thread_id uuid, agent_id uuid, resource_kind text, resource_key text, status text, lease_token uuid, lease_expires_at timestamptz, released_at timestamptz, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_thread_id uuid;
+  v_claim_id uuid;
+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 nullif(trim(p_resource_key), '') is null then
+    raise exception 'resource key is required' using errcode = '22023';
+  end if;
+
+  if p_task_id is not null then
+    select tasks.thread_id into v_thread_id from agent_board.tasks where id = p_task_id;
+    if v_thread_id is null then
+      raise exception 'task not found' using errcode = 'P0002';
+    end if;
+  else
+    v_thread_id := p_thread_id;
+  end if;
+
+  update agent_board.claims c
+     set status = 'expired',
+         updated_at = now()
+   where c.resource_kind = p_resource_kind
+     and c.resource_key = p_resource_key
+     and c.status = 'active'
+     and c.released_at is null
+     and c.lease_expires_at <= now();
+
+  if exists (
+    select 1 from agent_board.claims
+     where claims.resource_kind = p_resource_kind
+       and claims.resource_key = p_resource_key
+       and claims.status = 'active'
+       and claims.released_at is null
+       and claims.lease_expires_at > now()
+  ) then
+    raise exception 'conflicting active claim' using errcode = '23505';
+  end if;
+
+  insert into agent_board.claims(task_id, thread_id, agent_id, resource_kind, resource_key, lease_expires_at, metadata)
+  values (p_task_id, v_thread_id, p_agent_id, p_resource_kind, p_resource_key, p_lease_expires_at, coalesce(p_metadata, '{}'::jsonb))
+  returning id into v_claim_id;
+
+  if p_task_id is not null then
+    perform agent_board.append_task_event(p_task_id, p_agent_id, 'claimed', jsonb_build_object('claim_id', v_claim_id, 'resource_kind', p_resource_kind, 'resource_key', p_resource_key));
+  end if;
+
+  return query
+  select c.id, c.task_id, c.thread_id, c.agent_id, c.resource_kind, c.resource_key, c.status, c.lease_token, c.lease_expires_at, c.released_at, c.created_at, c.updated_at
+    from agent_board.claims c
+   where c.id = v_claim_id;
+end;
+$$;
+
+create or replace function agent_board.renew_claim(p_lease_token uuid, p_lease_expires_at timestamptz)
+returns table(claim_id uuid, task_id uuid, thread_id uuid, agent_id uuid, resource_kind text, resource_key text, status text, lease_token uuid, lease_expires_at timestamptz, released_at timestamptz, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  return query
+  update agent_board.claims c
+     set lease_expires_at = p_lease_expires_at,
+         updated_at = now()
+   where c.lease_token = p_lease_token
+     and c.status = 'active'
+     and c.released_at is null
+     and c.lease_expires_at > now()
+  returning c.id, c.task_id, c.thread_id, c.agent_id, c.resource_kind, c.resource_key, c.status, c.lease_token, c.lease_expires_at, c.released_at, c.created_at, c.updated_at;
+end;
+$$;
+
+create or replace function agent_board.release_claim(p_lease_token uuid)
+returns table(claim_id uuid, task_id uuid, thread_id uuid, agent_id uuid, resource_kind text, resource_key text, status text, lease_token uuid, lease_expires_at timestamptz, released_at timestamptz, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  return query
+  update agent_board.claims c
+     set status = 'released',
+         released_at = now(),
+         updated_at = now()
+   where c.lease_token = p_lease_token
+     and c.status = 'active'
+     and c.released_at is null
+  returning c.id, c.task_id, c.thread_id, c.agent_id, c.resource_kind, c.resource_key, c.status, c.lease_token, c.lease_expires_at, c.released_at, c.created_at, c.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(thread_id, agent_id, last_read_message_sequence, last_read_at)
+  values (p_thread_id, p_agent_id, v_sequence, now())
+  on conflict (thread_id, agent_id) do update
+    set last_read_message_sequence = greatest(read_receipts.last_read_message_sequence, excluded.last_read_message_sequence),
+        last_read_at = now()
+  returning read_receipts.thread_id, read_receipts.agent_id, read_receipts.last_read_message_sequence, read_receipts.last_read_at;
+end;
+$$;
+
+revoke all on schema agent_board from public, anon, authenticated;
+grant usage on schema agent_board to service_role;
+
+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/20260503000001_agent_board_coordination_rpcs.sql

@@ -0,0 +1,229 @@
+create or replace function agent_board.delegate_task(
+  p_parent_task_id uuid,
+  p_actor_agent_id uuid,
+  p_title text,
+  p_details text default null,
+  p_delegated_to_agent_id uuid default null,
+  p_priority text default 'medium',
+  p_note text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(delegation_id uuid, child_task_id uuid, parent_task_id uuid, root_task_id uuid, delegation_status text, child_event_sequence bigint, parent_event_sequence bigint, created_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_parent agent_board.tasks%rowtype;
+  v_child record;
+  v_delegation_id uuid;
+  v_parent_event record;
+begin
+  select * into v_parent from agent_board.tasks where id = p_parent_task_id;
+  if v_parent.id is null then
+    raise exception 'parent task not found' using errcode = 'P0002';
+  end if;
+
+  select * into v_child
+    from agent_board.create_task(v_parent.thread_id, p_actor_agent_id, p_title, p_details, p_delegated_to_agent_id, p_parent_task_id, p_priority, 'hierarchical', p_metadata);
+
+  insert into agent_board.delegations(parent_task_id, child_task_id, delegated_by_agent_id, delegated_to_agent_id, note, metadata)
+  values (p_parent_task_id, v_child.task_id, p_actor_agent_id, p_delegated_to_agent_id, p_note, coalesce(p_metadata, '{}'::jsonb))
+  returning id into v_delegation_id;
+
+  select * into v_parent_event
+    from agent_board.append_task_event(p_parent_task_id, p_actor_agent_id, 'delegated', jsonb_build_object('delegation_id', v_delegation_id, 'child_task_id', v_child.task_id));
+
+  return query
+  select v_delegation_id, v_child.task_id, p_parent_task_id, v_child.root_task_id, 'requested'::text, v_child.created_event_sequence, v_parent_event.event_sequence, now();
+end;
+$$;
+
+create or replace function agent_board.add_artifact(
+  p_created_by_agent_id uuid,
+  p_uri text,
+  p_artifact_type text default 'url',
+  p_storage_kind text default 'external_url',
+  p_thread_id uuid default null,
+  p_task_id uuid default null,
+  p_message_id uuid default null,
+  p_task_event_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(artifact_id uuid, task_event_sequence bigint, created_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_artifact_id uuid;
+  v_event record;
+begin
+  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;
+  if p_thread_id is null and p_task_id is null and p_message_id is null and p_task_event_id is null then
+    raise exception 'artifact target is required' using errcode = '22023';
+  end if;
+
+  insert into agent_board.artifacts(thread_id, task_id, message_id, task_event_id, created_by_agent_id, artifact_type, storage_kind, uri, metadata)
+  values (p_thread_id, p_task_id, p_message_id, p_task_event_id, p_created_by_agent_id, coalesce(p_artifact_type, 'url'), coalesce(p_storage_kind, 'external_url'), p_uri, coalesce(p_metadata, '{}'::jsonb))
+  returning id into v_artifact_id;
+
+  if p_task_id is not null then
+    select * into v_event
+      from agent_board.append_task_event(p_task_id, p_created_by_agent_id, 'artifact_added', jsonb_build_object('artifact_id', v_artifact_id));
+  end if;
+
+  return query
+  select v_artifact_id, v_event.event_sequence, now();
+end;
+$$;
+
+create or replace function agent_board.raise_conflict(
+  p_thread_id uuid,
+  p_raised_by_agent_id uuid,
+  p_summary text,
+  p_conflict_type text default 'other',
+  p_severity text default 'medium',
+  p_task_id uuid default null,
+  p_details jsonb default '{}'::jsonb
+)
+returns table(conflict_id uuid, status text, task_event_sequence bigint, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_conflict_id uuid;
+  v_event record;
+begin
+  insert into agent_board.conflicts(thread_id, task_id, raised_by_agent_id, summary, conflict_type, severity, details)
+  values (p_thread_id, p_task_id, p_raised_by_agent_id, p_summary, coalesce(p_conflict_type, 'other'), coalesce(p_severity, 'medium'), coalesce(p_details, '{}'::jsonb))
+  returning id into v_conflict_id;
+
+  if p_task_id is not null then
+    select * into v_event
+      from agent_board.append_task_event(p_task_id, p_raised_by_agent_id, 'conflict_raised', jsonb_build_object('conflict_id', v_conflict_id));
+  end if;
+
+  return query
+  select c.id, c.status, v_event.event_sequence, c.created_at, c.updated_at
+    from agent_board.conflicts c
+   where c.id = v_conflict_id;
+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 where id = p_conflict_id and status <> 'resolved';
+  if v_conflict.id is null then
+    raise exception 'conflict not found' using errcode = 'P0002';
+  end if;
+
+  update agent_board.conflicts
+     set status = 'resolved',
+         resolved_by_agent_id = p_resolved_by_agent_id,
+         resolved_at = now(),
+         details = details || coalesce(p_details, '{}'::jsonb),
+         updated_at = now()
+   where 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.raise_escalation(
+  p_thread_id uuid,
+  p_raised_by_agent_id uuid,
+  p_summary text,
+  p_escalation_type text default 'other',
+  p_severity text default 'medium',
+  p_task_id uuid default null,
+  p_assigned_agent_id uuid default null,
+  p_details jsonb default '{}'::jsonb
+)
+returns table(escalation_id uuid, status text, task_event_sequence bigint, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_escalation_id uuid;
+  v_event record;
+begin
+  insert into agent_board.escalations(thread_id, task_id, raised_by_agent_id, assigned_agent_id, summary, escalation_type, severity, details)
+  values (p_thread_id, p_task_id, p_raised_by_agent_id, p_assigned_agent_id, p_summary, coalesce(p_escalation_type, 'other'), coalesce(p_severity, 'medium'), coalesce(p_details, '{}'::jsonb))
+  returning id into v_escalation_id;
+
+  if p_task_id is not null then
+    select * into v_event
+      from agent_board.append_task_event(p_task_id, p_raised_by_agent_id, 'escalated', jsonb_build_object('escalation_id', v_escalation_id));
+  end if;
+
+  return query
+  select e.id, e.status, v_event.event_sequence, e.created_at, e.updated_at
+    from agent_board.escalations e
+   where e.id = v_escalation_id;
+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 where id = p_escalation_id and status <> 'resolved';
+  if v_escalation.id is null then
+    raise exception 'escalation not found' using errcode = 'P0002';
+  end if;
+
+  update agent_board.escalations
+     set status = 'resolved',
+         resolved_by_agent_id = p_resolved_by_agent_id,
+         resolved_at = now(),
+         details = details || coalesce(p_details, '{}'::jsonb),
+         updated_at = now()
+   where 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;
+$$;
+
+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;