@consiliency/agent-board-schema 1.64.0 → 1.74.0

package/migrations/20261104170000_agent_board_tasking_replay_scope.sql

@@ -0,0 +1,320 @@
+-- #717 F2: same-key tasking replay must not widen a task's delivery scope.
+--
+-- create_tasking_delivery keys idempotency on (thread, resolved creator, key) and, on a replay,
+-- reused the task and fanned it out to whatever audience the RETRY named. A recipient-only task
+-- replayed with a board target therefore became readable by board members, and through the hosted
+-- delegate policies (which key on a board-scoped delivery of the task) by that board's delegates,
+-- together with the task history other agents authored on it.
+--
+-- The identity, the advisory lock and the lookup are unchanged; board_id is deliberately NOT added
+-- to the key, which would silently turn a retry into a second task. A replay may name the same
+-- audience or a subset of it, and a same-board replay still fans out to the board's CURRENT members,
+-- as before. Anything the persisted deliveries do not already prove is refused with 42501 before any
+-- replay side effect, and the raise rolls back the whole call, including any first association,
+-- telemetry, and the signed wrappers' evidence (they do not catch). Compatibility limit, recorded:
+-- a task whose deliveries were never written or were removed cannot be replayed with any target.
+
+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::text, p_recipient_agent_ids uuid[] DEFAULT NULL::uuid[], p_board_id uuid DEFAULT NULL::uuid, p_priority text DEFAULT 'medium'::text, p_orchestration_mode text DEFAULT 'distributed'::text, p_idempotency_key text DEFAULT NULL::text, 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 timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+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), '');
+  v_actor_agent_id uuid;
+  v_is_creator boolean;
+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_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 agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  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 then
+    if not exists (select 1 from agent_board.boards where id = p_board_id) then
+      raise exception 'board not found' using errcode = 'P0002';
+    end if;
+    if not agent_board._current_agent_has_board_access(p_board_id) then
+      raise exception 'board not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_send_to_board(p_board_id) then
+      raise exception 'board send requires a non-observer board role' using errcode = '42501';
+    end if;
+  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;
+
+  if agent_board._is_service_role() then
+    perform agent_board._record_send_authz_telemetry(
+      'service_role_bypass',
+      coalesce(nullif(p_metadata -> 'signed_write' ->> 'origin', ''), 'unknown'),
+      v_actor_agent_id,
+      p_board_id,
+      'create_tasking_delivery',
+      agent_board._resolve_send_fleet_scope(v_actor_agent_id),
+      null,
+      jsonb_build_object('redacted', true)
+    );
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'create_tasking_delivery:' || p_thread_id::text || ':' || v_actor_agent_id::text,
+    v_idempotency_key
+  );
+
+  if p_board_id is not null then
+    perform agent_board._associate_empty_thread(p_thread_id, p_board_id);
+    -- Both checks are new statements after the thread-lock wait.
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_has_board_access(p_board_id) then
+      raise exception 'board not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_send_to_board(p_board_id) then
+      raise exception 'board send requires a non-observer board role' using errcode = '42501';
+    end if;
+  end if;
+
+  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 = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'create_tasking_delivery'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc, id 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,
+        v_actor_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
+    -- #717 F2: a replay reuses the task, so it may not widen who can read it. The audience a
+    -- replay may name is bounded by the task's PERSISTED tasking deliveries: a board only if a
+    -- board-scoped delivery of this task already names it, and each explicit recipient only if
+    -- it already holds a private (null-board) delivery of this task. Thread stamps and task or
+    -- caller metadata are never evidence: metadata is writable through other task creators.
+    -- Missing evidence refuses; a new audience needs a new idempotency key (a new task).
+    if (
+      p_board_id is not null
+      and not exists (
+        select 1
+          from agent_board.delivery_recipients dr
+         where dr.source_task_id = v_task.id
+           and dr.delivery_mode = 'tasking'
+           and dr.board_id = p_board_id
+      )
+    ) or exists (
+      select 1
+        from unnest(coalesce(v_recipient_ids, '{}'::uuid[])) as requested(agent_id)
+       where not exists (
+         select 1
+           from agent_board.delivery_recipients dr
+          where dr.source_task_id = v_task.id
+            and dr.delivery_mode = 'tasking'
+            and dr.recipient_agent_id = requested.agent_id
+            and dr.board_id is null
+       )
+    ) then
+      raise exception 'tasking replay cannot widen delivery scope' using errcode = '42501';
+    end if;
+
+    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
+      -- #608: the board fan-out does not deliver a task to the agent that created it. The
+      -- creator's row is KEPT, feed-only, exactly as a board post's author row is. Before #667,
+      -- _upsert_delivery_recipient was the only board-stamp path; skipping that row
+      -- left a creator-only board's thread unlinked and post_message on the access-only branch of
+      -- the observer gate (codex and grok seats, PR #615 round 1). It also keeps the board
+      -- directory's activity and delegate visibility as they were. An explicit recipient list
+      -- naming the creator still delivers to it: that is the caller addressing itself, and the
+      -- board loop must not then demote the row the explicit loop wrote. It shares that row (the
+      -- delivery upsert keeps the explicit row's null board_id), so demoting it wrote both
+      -- visibility flags false and violated inbox_items_visibility_shape, aborting the whole task
+      -- (every seat on PR #615 round 2).
+      v_is_creator := v_membership.agent_id is not distinct from v_actor_agent_id
+        and not (v_membership.agent_id = any(coalesce(v_recipient_ids, '{}'::uuid[])));
+      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,
+        not v_is_creator,
+        v_recipient.board_id is not null,
+        v_fetch_descriptor,
+        jsonb_build_object('threadId', p_thread_id::text, 'boardId', p_board_id::text)
+      );
+
+      -- The counts are of RECIPIENTS; the creator's feed-only row is not one.
+      if not v_is_creator then
+        v_delivered_count := v_delivered_count + 1;
+        v_inbox_count := v_inbox_count + 1;
+      end if;
+      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;
+$function$
+;
+
+revoke all on function agent_board.create_tasking_delivery(uuid,uuid,text,text,uuid[],uuid,text,text,text,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.create_tasking_delivery(uuid,uuid,text,text,uuid[],uuid,text,text,text,jsonb) to "service_role";
+grant execute on function agent_board.create_tasking_delivery(uuid,uuid,text,text,uuid[],uuid,text,text,text,jsonb) to "authenticated";
+comment on function agent_board.create_tasking_delivery(uuid,uuid,text,text,uuid[],uuid,text,text,text,jsonb) is 'Creates or reuses a tasking send after validating the session actor and any board target. First board association precedes its own task and event writes; explicit recipient delivery rows preserve their private scope. A replay of an existing (thread, creator, key) cannot widen the task''s audience (#717 F2): a board must already hold a board-scoped tasking delivery of the task and each explicit recipient a private one, else 42501 ''tasking replay cannot widen delivery scope'' before any replay effect; a new audience needs a new key.';

package/migrations/20261104180000_agent_board_delivery_writer_execute.sql

@@ -0,0 +1,51 @@
+-- DELIVERYWRITEREXEC (#717 F1): the internal message/delivery/inbox writers are not API routes.
+--
+-- Five SECURITY DEFINER helpers write the delivery sinks (delivery_recipients, inbox_items,
+-- callback_outbox_events) or the thread message sequence, and each takes its authority from its
+-- ARGUMENTS: a recipient, a board, a membership, a message id, a subject. They were EXECUTE-able
+-- by service_role through the schema-wide `grant execute on all functions in schema agent_board
+-- to service_role` of the 2026-05 migrations, never by a deliberate grant.
+--
+-- Called directly there is no sending RPC in front of them, so nothing checks that the caller is
+-- the author, that the recipient was addressed, or that the board was targeted. #717 measured it
+-- (review S4/S4b): `_upsert_delivery_recipient('board', member, 'message', <a DM on a board
+-- thread>, …)` returned OK and a board member then read the DM; `'direct'` mode re-addressed the
+-- same DM to an arbitrary agent. Both keep the ORIGINAL author on the message row, so the
+-- republished DM reads as authored by its sender. `_upsert_inbox_item`, `_queue_inbox_callbacks`,
+-- `_queue_board_post_callbacks` (forged wake payloads, caller-chosen subject and preview against
+-- a real message id) and `_next_thread_message_sequence` (sequence consumption on any thread)
+-- are the same class: internal, argument-authorised, reachable only because of the blanket grant.
+--
+-- The class is catalog-derived in tests/agent_board_delivery_writer_execute.test.sql (DWX):
+-- every routine that writes a message/delivery/inbox sink, directly or transitively, either has
+-- no API-role EXECUTE or is a named, positively-asserted public route. No caller outside the
+-- schema invokes any of these five (repository and Portal searched; edge functions call fixed
+-- public RPC names). The public send routes keep working: they are SECURITY DEFINER and reach the
+-- helpers as the function owner, not as the API caller.
+--
+-- No function body changes, so the source tree's existing definitions stay the sole ones.
+
+revoke all on function agent_board._upsert_delivery_recipient(text,uuid,text,uuid,uuid,uuid,uuid,uuid,jsonb)
+  from public, anon, authenticated, service_role, agent_board_delegate;
+comment on function agent_board._upsert_delivery_recipient(text,uuid,text,uuid,uuid,uuid,uuid,uuid,jsonb) is
+  'Internal delivery sink, not an API route: no API role may EXECUTE it (#717 F1). Enforces thread/board identity and the locked empty-history boundary for message, task and delegation delivery sources. Supplying a source ID does not exempt its private history. The sending RPC validates caller authority before its own writes.';
+
+revoke all on function agent_board._upsert_inbox_item(uuid,uuid,uuid,text,text,uuid,uuid,uuid,text,text,text,boolean,boolean,jsonb,jsonb)
+  from public, anon, authenticated, service_role, agent_board_delegate;
+comment on function agent_board._upsert_inbox_item(uuid,uuid,uuid,text,text,uuid,uuid,uuid,text,text,text,boolean,boolean,jsonb,jsonb) is
+  'Internal inbox sink, not an API route: no API role may EXECUTE it (#717 F1). The sole inbox_items inserter; its recipient, board, visibility and preview are trusted from the calling send/tasking RPC, which validated caller authority first.';
+
+revoke all on function agent_board._queue_inbox_callbacks(uuid,text)
+  from public, anon, authenticated, service_role, agent_board_delegate;
+comment on function agent_board._queue_inbox_callbacks(uuid,text) is
+  'Internal callback sink, not an API route: no API role may EXECUTE it (#717 F1). Queues inbox callback outbox events for an inbox item the calling delivery RPC has just written.';
+
+revoke all on function agent_board._queue_board_post_callbacks(uuid,uuid,text,text,text,jsonb)
+  from public, anon, authenticated, service_role, agent_board_delegate;
+comment on function agent_board._queue_board_post_callbacks(uuid,uuid,text,text,text,jsonb) is
+  'Internal callback sink, not an API route: no API role may EXECUTE it (#717 F1). Queues board-post callback outbox events with the subject, preview and fetch descriptor supplied by the board delivery that called it.';
+
+revoke all on function agent_board._next_thread_message_sequence(uuid)
+  from public, anon, authenticated, service_role, agent_board_delegate;
+comment on function agent_board._next_thread_message_sequence(uuid) is
+  'Internal sequence writer, not an API route: no API role may EXECUTE it (#717 F1). Advances threads.last_message_sequence under the thread row lock for the message insertion that called it.';