@desplega.ai/agent-swarm 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "agent-swarm.dev — an open-source operating system for AI work: a lead agent breaks goals into tasks, routes them to specialized workers such as Claude Code or Codex, runs each worker in an isolated container, and preserves shared memory, tools, schedules, and review gates so delegated work compounds across sessions.",
   "keywords": [
     "agent-swarm.dev",

package/src/apps/action-caller.ts

@@ -0,0 +1,6 @@
+export type AppActionCaller = {
+  kind: "user" | "agent" | "operator" | "guest";
+  id: string | null;
+  name?: string;
+  pageId?: string;
+};

package/src/apps/script-types.ts

@@ -8,6 +8,13 @@ const APP_TYPES_PREAMBLE = `// ── Swarm Apps: generated per-app types (sourc
 // Rows are the app's declared columns plus the 5 system columns. Query
 // overloads narrow only when appId AND query are string literals.
 
+export type AppActionCaller = {
+  kind: "user" | "agent" | "operator" | "guest";
+  id: string | null;
+  name?: string;
+  pageId?: string;
+};
+
 export interface SwarmAppQueryResult<Row> {
   success: boolean;
   status: number;
@@ -175,9 +182,8 @@ function renderQuery(
 }
 
 function renderApp(app: AppRecord, namespace: string): string {
-  // Reserve the generated alias so a model named `actionName` dedupes to
-  // `ActionName_2` instead of colliding with `type ActionName`.
-  const modelNames = new Set<string>(["ActionName"]);
+  // Reserve action types so model names cannot collide with them.
+  const modelNames = new Set<string>(["ActionName", "ActionArgs", "AppActionCaller"]);
   const renderedModels = Object.entries(app.definition.models).map(([modelName, model]) =>
     renderModel(modelName, model, modelNames),
   );
@@ -202,6 +208,13 @@ ${renderedModels.map((model) => model.source).join("\n\n")}
 
   /** Declared actions. Invocation is REST-only: POST /api/apps/<id>/actions/<name>. */
   export type ActionName = ${actionType};
+
+  /** Script action arguments include server-stamped app and caller context. */
+  export interface ActionArgs {
+    app: { id: ${JSON.stringify(app.id)} };
+    caller: AppActionCaller;
+    [key: string]: unknown;
+  }
 }
 
 export interface SwarmSdk {

package/src/be/db/active-sessions.ts

@@ -1,3 +1,4 @@
+import type { ActiveSession } from "../../types";
 import { getDbClient } from "./runtime";
 
 /**
@@ -28,3 +29,7 @@ export async function refreshActiveSessionOnActivity(
   );
   return result.changes > 0;
 }
+
+export async function getActiveSessionById(id: string): Promise<ActiveSession | null> {
+  return getDbClient().get<ActiveSession>("SELECT * FROM active_sessions WHERE id = ?", [id]);
+}

package/src/be/db/session-visibility.ts

@@ -0,0 +1,29 @@
+/**
+ * Session-list visibility for session sharing. `all`: sessions the viewer
+ * owns, ownerless sessions, and sessions shared with the viewer or everyone.
+ * `mine`: owned by the viewer. `shared`: owned by someone else and shared with
+ * the viewer or everyone. A null `userId` (a guest page session) owns nothing.
+ */
+export type SessionViewer = { userId: string | null; scope: "all" | "mine" | "shared" };
+
+/** SQL condition + params restricting root tasks (alias `r`) to what `viewer` may open. */
+export function sessionViewerCondition(viewer: SessionViewer): {
+  sql: string;
+  params: (string | null)[];
+} {
+  const shared = `EXISTS (SELECT 1 FROM session_shares s
+      WHERE s.rootTaskId = r.id AND s.revokedAt IS NULL AND (s.userId IS NULL OR s.userId = ?))`;
+  if (viewer.scope === "mine") {
+    return { sql: "r.requestedByUserId = ?", params: [viewer.userId] };
+  }
+  if (viewer.scope === "shared") {
+    return {
+      sql: `(r.requestedByUserId IS NOT NULL AND r.requestedByUserId IS NOT ? AND ${shared})`,
+      params: [viewer.userId, viewer.userId],
+    };
+  }
+  return {
+    sql: `(r.requestedByUserId IS NULL OR r.requestedByUserId = ? OR ${shared})`,
+    params: [viewer.userId, viewer.userId],
+  };
+}

package/src/be/db/tasks/read.ts

@@ -556,10 +556,14 @@ export async function hasNonTerminalRerouteDecisionChild(parentId: string): Prom
   return row !== undefined && row !== null;
 }
 
-export async function getTasksByAgentId(agentId: string): Promise<AgentTask[]> {
+export async function getTasksByAgentId(
+  agentId: string,
+  readableBy?: { userId: string | null },
+): Promise<AgentTask[]> {
+  const readable = readableBy ? readableSessionCondition(readableBy.userId) : undefined;
   const rows = await getDbClient().query<AgentTaskRow>(
-    "SELECT * FROM agent_tasks WHERE agentId = ? ORDER BY createdAt DESC",
-    [agentId],
+    `SELECT * FROM agent_tasks WHERE agentId = ?${readable ? ` AND ${readable.sql}` : ""} ORDER BY createdAt DESC`,
+    [agentId, ...(readable?.params ?? [])],
   );
   return rows.map(rowToAgentTask);
 }
@@ -642,6 +646,48 @@ export interface TaskFilters {
   limit?: number;
   offset?: number;
   includeHeartbeat?: boolean;
+  /** Only tasks of sessions this user may read; `userId: null` is a guest. */
+  readableBy?: { userId: string | null };
+}
+
+/**
+ * The SQL twin of `sessionAccessForRoot` (../../session-shares). A session's
+ * root is its topmost existing task; the session is hidden when the root has
+ * an owner other than the user and no active share names the user or
+ * everyone. Descending from hidden roots is linear in their tasks at any chain
+ * depth, and as a WHERE term it keeps paging and `COUNT(*)` on the same rows.
+ * `parentTaskId` is fixed at insert to an existing task, so no parent cycle
+ * (which would have no root) can form.
+ *
+ * `taskIdColumn` applies the same filter to any table keyed by task id. A
+ * nullable column keeps its task-less rows: they belong to no session.
+ */
+export function readableSessionCondition(
+  userId: string | null,
+  taskIdColumn = "agent_tasks.id",
+  opts: { nullable?: boolean } = {},
+): { sql: string; params: string[] } {
+  const otherOwner = userId
+    ? "r.requestedByUserId IS NOT NULL AND r.requestedByUserId != ?"
+    : "r.requestedByUserId IS NOT NULL";
+  const shareMatch = userId ? "(s.userId IS NULL OR s.userId = ?)" : "s.userId IS NULL";
+  const notHidden = `${taskIdColumn} NOT IN (
+      WITH RECURSIVE hidden(id) AS (
+        SELECT r.id FROM agent_tasks r
+        WHERE (r.parentTaskId IS NULL
+            OR NOT EXISTS (SELECT 1 FROM agent_tasks p WHERE p.id = r.parentTaskId))
+          AND ${otherOwner}
+          AND NOT EXISTS (SELECT 1 FROM session_shares s
+            WHERE s.rootTaskId = r.id AND s.revokedAt IS NULL AND ${shareMatch})
+        UNION ALL
+        SELECT c.id FROM agent_tasks c JOIN hidden ON c.parentTaskId = hidden.id
+      )
+      SELECT id FROM hidden
+    )`;
+  return {
+    sql: opts.nullable ? `(${taskIdColumn} IS NULL OR ${notHidden})` : notHidden,
+    params: userId ? [userId, userId] : [],
+  };
 }
 
 export function getAllTasks(filters?: TaskFilters): Promise<AgentTask[]>;
@@ -756,6 +802,12 @@ export async function getAllTasks(
     );
   }
 
+  if (filters?.readableBy) {
+    const readable = readableSessionCondition(filters.readableBy.userId);
+    conditions.push(readable.sql);
+    params.push(...readable.params);
+  }
+
   const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const limit = filters?.limit ?? 25;
   const offset = filters?.offset ?? 0;
@@ -916,6 +968,12 @@ export async function getTasksCount(
     );
   }
 
+  if (filters?.readableBy) {
+    const readable = readableSessionCondition(filters.readableBy.userId);
+    conditions.push(readable.sql);
+    params.push(...readable.params);
+  }
+
   const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const query = `SELECT COUNT(*) as count FROM agent_tasks ${whereClause}`;
 

package/src/be/db/tasks/write.ts

@@ -27,6 +27,7 @@ import {
   type AgentTaskRow,
   getTaskById,
   NEVER_STARTED_TASK_STATUSES,
+  readableSessionCondition,
   rowToAgentTask,
 } from "./read";
 
@@ -1019,12 +1020,16 @@ export async function resumeTask(taskId: string): Promise<AgentTask | null> {
  * Used on startup to resume tasks that were interrupted by deployment.
  * Returns tasks ordered by creation time (oldest first for FIFO).
  */
-export async function getPausedTasksForAgent(agentId: string): Promise<AgentTask[]> {
+export async function getPausedTasksForAgent(
+  agentId: string,
+  readableBy?: { userId: string | null },
+): Promise<AgentTask[]> {
+  const readable = readableBy ? readableSessionCondition(readableBy.userId) : undefined;
   const rows = await getDbClient().query<AgentTaskRow>(
     `SELECT * FROM agent_tasks
-       WHERE agentId = ? AND status = 'paused'
+       WHERE agentId = ? AND status = 'paused'${readable ? ` AND ${readable.sql}` : ""}
        ORDER BY createdAt ASC, rowid ASC`,
-    [agentId],
+    [agentId, ...(readable?.params ?? [])],
   );
   return rows.map(rowToAgentTask);
 }
@@ -1093,15 +1098,19 @@ export async function resetOrphanedInProgressTasksForAgent(
  * Used by hooks to detect task cancellation and stop the worker loop.
  * Returns tasks cancelled within the last 5 minutes.
  */
-export async function getRecentlyCancelledTasksForAgent(agentId: string): Promise<AgentTask[]> {
+export async function getRecentlyCancelledTasksForAgent(
+  agentId: string,
+  readableBy?: { userId: string | null },
+): Promise<AgentTask[]> {
   const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString();
+  const readable = readableBy ? readableSessionCondition(readableBy.userId) : undefined;
   const rows = await getDbClient().query<AgentTaskRow>(
     `SELECT * FROM agent_tasks
        WHERE agentId = ?
        AND status = 'cancelled'
-       AND finishedAt > ?
+       AND finishedAt > ?${readable ? ` AND ${readable.sql}` : ""}
        ORDER BY finishedAt DESC`,
-    [agentId, fiveMinutesAgo],
+    [agentId, fiveMinutesAgo, ...(readable?.params ?? [])],
   );
   return rows.map(rowToAgentTask);
 }

package/src/be/db.ts

@@ -195,6 +195,7 @@ import {
 } from "./db/context-versions";
 import { clearAgentModelProfileOnOverrideChange } from "./db/model-profiles";
 import { getDb, getDbClient } from "./db/runtime";
+import { type SessionViewer, sessionViewerCondition } from "./db/session-visibility";
 import { classifyTaskHumanFree, reclassifyTaskHumanFree } from "./db/tasks/human-free";
 import {
   type AgentTaskRow,
@@ -203,6 +204,7 @@ import {
   findExistingLinearTrackerContextWork,
   getTaskById,
   getTasksByAgentId,
+  readableSessionCondition,
   rowToAgentTask,
   rowToAgentTaskSummary,
 } from "./db/tasks/read";
@@ -2081,13 +2083,17 @@ export async function getPendingSteeringForTask(taskId: string): Promise<Steerin
   return await getSteeringMessagesForTask(taskId, { status: "pending" });
 }
 
-export async function getPendingSteeringForAgent(agentId: string): Promise<SteeringMessage[]> {
+export async function getPendingSteeringForAgent(
+  agentId: string,
+  readableBy?: { userId: string | null },
+): Promise<SteeringMessage[]> {
+  const readable = readableBy ? readableSessionCondition(readableBy.userId, "t.id") : undefined;
   const rows = await getDbClient().query<TaskSteeringMessageRow>(
     `${STEERING_MESSAGE_SELECT}
        JOIN agent_tasks t ON t.id = m.task_id
-       WHERE t.agentId = ? AND m.status = 'pending'
+       WHERE t.agentId = ? AND m.status = 'pending'${readable ? ` AND ${readable.sql}` : ""}
        ORDER BY m.created_at ASC, m.rowid ASC`,
-    [agentId],
+    [agentId, ...(readable?.params ?? [])],
   );
   return rows.map(rowToSteeringMessage);
 }
@@ -2185,27 +2191,33 @@ export async function hasPendingSteering(taskId: string): Promise<boolean> {
 // Combined Queries (Agent with Tasks)
 // ============================================================================
 
-export async function getAgentWithTasks(id: string): Promise<AgentWithTasks | null> {
+export async function getAgentWithTasks(
+  id: string,
+  readableBy?: { userId: string | null },
+): Promise<AgentWithTasks | null> {
   return await getDbClient().transaction(
     async () => {
       const agent = await getAgentById(id);
       if (!agent) return null;
 
-      const tasks = await getTasksByAgentId(id);
+      const tasks = await getTasksByAgentId(id, readableBy);
       return { ...agent, tasks };
     },
     { readOnly: true },
   );
 }
 
-export async function getAllAgentsWithTasks(opts?: { slim?: boolean }): Promise<AgentWithTasks[]> {
+export async function getAllAgentsWithTasks(opts?: {
+  slim?: boolean;
+  readableBy?: { userId: string | null };
+}): Promise<AgentWithTasks[]> {
   return await getDbClient().transaction(
     async () => {
       const agents = await getAllAgents({ slim: opts?.slim ?? false });
       return await Promise.all(
         agents.map(async (agent) => ({
           ...agent,
-          tasks: await getTasksByAgentId(agent.id),
+          tasks: await getTasksByAgentId(agent.id, opts?.readableBy),
         })),
       );
     },
@@ -2268,10 +2280,16 @@ export async function createLogEntry(entry: {
   return rowToAgentLog(row);
 }
 
-export async function getLogsByAgentId(agentId: string): Promise<AgentLog[]> {
+export async function getLogsByAgentId(
+  agentId: string,
+  readableBy?: { userId: string | null },
+): Promise<AgentLog[]> {
+  const readable = readableBy
+    ? readableSessionCondition(readableBy.userId, "agent_log.taskId", { nullable: true })
+    : undefined;
   const rows = await getDbClient().query<AgentLogRow>(
-    "SELECT * FROM agent_log WHERE agentId = ? ORDER BY createdAt DESC",
-    [agentId],
+    `SELECT * FROM agent_log WHERE agentId = ?${readable ? ` AND ${readable.sql}` : ""} ORDER BY createdAt DESC`,
+    [agentId, ...(readable?.params ?? [])],
   );
   return rows.map(rowToAgentLog);
 }
@@ -2315,16 +2333,24 @@ export async function getLogsByEventType(eventType: AgentLogEventType): Promise<
   return rows.map(rowToAgentLog);
 }
 
-export async function getAllLogs(limit?: number): Promise<AgentLog[]> {
+export async function getAllLogs(
+  limit?: number,
+  readableBy?: { userId: string | null },
+): Promise<AgentLog[]> {
+  const readable = readableBy
+    ? readableSessionCondition(readableBy.userId, "agent_log.taskId", { nullable: true })
+    : undefined;
+  const readableParams = readable?.params ?? [];
   if (limit) {
     const rows = await getDbClient().query<AgentLogRow>(
-      "SELECT * FROM agent_log WHERE eventType != 'agent_status_change' ORDER BY createdAt DESC LIMIT ?",
-      [limit],
+      `SELECT * FROM agent_log WHERE eventType != 'agent_status_change'${readable ? ` AND ${readable.sql}` : ""} ORDER BY createdAt DESC LIMIT ?`,
+      [...readableParams, limit],
     );
     return rows.map(rowToAgentLog);
   }
   const rows = await getDbClient().query<AgentLogRow>(
-    "SELECT * FROM agent_log ORDER BY createdAt DESC",
+    `SELECT * FROM agent_log${readable ? ` WHERE ${readable.sql}` : ""} ORDER BY createdAt DESC`,
+    readableParams,
   );
   return rows.map(rowToAgentLog);
 }
@@ -5820,8 +5846,13 @@ export interface ConcurrentContext {
  * Returns processing inbox messages, recent task delegations by leads,
  * and currently active (in-progress) tasks across the swarm.
  */
-export async function getConcurrentContext(): Promise<ConcurrentContext> {
+export async function getConcurrentContext(readableBy?: {
+  userId: string | null;
+}): Promise<ConcurrentContext> {
   const client = getDbClient();
+  const readable = readableBy ? readableSessionCondition(readableBy.userId, "t.id") : undefined;
+  const readableSql = readable ? ` AND ${readable.sql}` : "";
+  const readableParams = readable?.params ?? [];
 
   // 1. Inbox messages currently being processed (status = 'processing')
   const processingInboxMessages = await client.query<{
@@ -5850,9 +5881,9 @@ export async function getConcurrentContext(): Promise<ConcurrentContext> {
        FROM agent_tasks t
        LEFT JOIN agents a ON t.agentId = a.id
        WHERE t.createdAt > ?
-         AND t.creatorAgentId IN (SELECT id FROM agents WHERE isLead = 1)
+         AND t.creatorAgentId IN (SELECT id FROM agents WHERE isLead = 1)${readableSql}
        ORDER BY t.createdAt DESC`,
-    [fiveMinutesAgo],
+    [fiveMinutesAgo, ...readableParams],
   );
 
   // 3. Currently in-progress tasks across the swarm
@@ -5868,8 +5899,9 @@ export async function getConcurrentContext(): Promise<ConcurrentContext> {
     `SELECT t.id, t.task, t.agentId, a.name as agentName, t.status, t.createdAt, t.progress
        FROM agent_tasks t
        LEFT JOIN agents a ON t.agentId = a.id
-       WHERE t.status = 'in_progress'
+       WHERE t.status = 'in_progress'${readableSql}
        ORDER BY t.createdAt DESC`,
+    readableParams,
   );
 
   return {
@@ -7157,15 +7189,27 @@ export async function deleteActiveSessionById(id: string): Promise<boolean> {
   return result.changes > 0;
 }
 
-export async function getActiveSessions(agentId?: string): Promise<ActiveSession[]> {
+export async function getActiveSessions(
+  agentId?: string,
+  readableBy?: { userId: string | null },
+): Promise<ActiveSession[]> {
+  const conditions: string[] = [];
+  const params: string[] = [];
   if (agentId) {
-    return await getDbClient().query<ActiveSession>(
-      "SELECT * FROM active_sessions WHERE agentId = ? ORDER BY startedAt DESC",
-      [agentId],
-    );
+    conditions.push("agentId = ?");
+    params.push(agentId);
   }
+  if (readableBy) {
+    const readable = readableSessionCondition(readableBy.userId, "active_sessions.taskId", {
+      nullable: true,
+    });
+    conditions.push(readable.sql);
+    params.push(...readable.params);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   return await getDbClient().query<ActiveSession>(
-    "SELECT * FROM active_sessions ORDER BY startedAt DESC",
+    `SELECT * FROM active_sessions ${where} ORDER BY startedAt DESC`,
+    params,
   );
 }
 
@@ -12905,6 +12949,8 @@ interface ListRecentSessionsOpts {
   contextKeyPrefix?: string;
   /** When true, return slim `SessionListItemSummary` rows (default: full). */
   slim?: boolean;
+  /** Restrict to sessions this viewer may open (session sharing). */
+  viewer?: SessionViewer;
 }
 
 export async function listRecentSessions(
@@ -12923,7 +12969,7 @@ export async function listRecentSessions(
   const requestedByUserId = opts?.requestedByUserId?.trim() || undefined;
 
   const conditions: string[] = ["r.parentTaskId IS NULL"];
-  const params: (string | number)[] = [];
+  const params: (string | number | null)[] = [];
 
   if (sources.length > 0) {
     conditions.push(`r.source IN (${sources.map(() => "?").join(", ")})`);
@@ -12942,6 +12988,11 @@ export async function listRecentSessions(
     conditions.push(`r.contextKey LIKE ? ESCAPE '\\'`);
     params.push(literalPrefixPattern(opts.contextKeyPrefix));
   }
+  if (opts?.viewer) {
+    const viewer = sessionViewerCondition(opts.viewer);
+    conditions.push(viewer.sql);
+    params.push(...viewer.params);
+  }
   params.push(limit, offset);
 
   const rootRows = await getDbClient().query<
@@ -13013,35 +13064,43 @@ export async function listRecentSessions(
  * a plain count, no recursive chain walk needed.
  */
 export async function countSessions(
-  opts?: Pick<ListRecentSessionsOpts, "source" | "q" | "requestedByUserId" | "contextKeyPrefix">,
+  opts?: Pick<
+    ListRecentSessionsOpts,
+    "source" | "q" | "requestedByUserId" | "contextKeyPrefix" | "viewer"
+  >,
 ): Promise<number> {
   const sources = opts?.source?.filter((s) => s.length > 0) ?? [];
   const q = opts?.q?.trim();
   const requestedByUserId = opts?.requestedByUserId?.trim() || undefined;
 
-  const conditions: string[] = ["parentTaskId IS NULL"];
-  const params: string[] = [];
+  const conditions: string[] = ["r.parentTaskId IS NULL"];
+  const params: (string | null)[] = [];
 
   if (sources.length > 0) {
-    conditions.push(`source IN (${sources.map(() => "?").join(", ")})`);
+    conditions.push(`r.source IN (${sources.map(() => "?").join(", ")})`);
     params.push(...sources);
   }
   if (q && q.length > 0) {
-    conditions.push("(lower(task) LIKE ? OR lower(COALESCE(title, '')) LIKE ?)");
+    conditions.push("(lower(r.task) LIKE ? OR lower(COALESCE(r.title, '')) LIKE ?)");
     const like = `%${q.toLowerCase()}%`;
     params.push(like, like);
   }
   if (requestedByUserId) {
-    conditions.push("requestedByUserId = ?");
+    conditions.push("r.requestedByUserId = ?");
     params.push(requestedByUserId);
   }
   if (opts?.contextKeyPrefix) {
-    conditions.push(`contextKey LIKE ? ESCAPE '\\'`);
+    conditions.push(`r.contextKey LIKE ? ESCAPE '\\'`);
     params.push(literalPrefixPattern(opts.contextKeyPrefix));
   }
+  if (opts?.viewer) {
+    const viewer = sessionViewerCondition(opts.viewer);
+    conditions.push(viewer.sql);
+    params.push(...viewer.params);
+  }
 
   const row = await getDbClient().get<{ count: number }>(
-    `SELECT COUNT(*) AS count FROM agent_tasks WHERE ${conditions.join(" AND ")}`,
+    `SELECT COUNT(*) AS count FROM agent_tasks r WHERE ${conditions.join(" AND ")}`,
     params,
   );
   return row?.count ?? 0;

package/src/be/events.ts

@@ -1,6 +1,7 @@
 import type { EventCategory, EventName, EventSource, EventStatus, SwarmEvent } from "../types";
 import { type ScrubbedText, scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 import { getDbClient } from "./db";
+import { readableSessionCondition } from "./db/tasks/read";
 import type { DbExecutor } from "./db-client";
 import { breaksJsonValidity } from "./scrub-json";
 import { recordSkillInvocation } from "./skill-invocations";
@@ -262,10 +263,20 @@ export async function getEventsFiltered(filters: {
    * the agent's event history.
    */
   latestPerDataField?: { events: EventName[]; dataFields: string[] };
+  /** Only events outside sessions this user may not read; `userId: null` is a guest. */
+  readableBy?: { userId: string | null };
 }): Promise<SwarmEvent[]> {
   const conditions: string[] = [];
   const params: (string | number)[] = [];
 
+  if (filters.readableBy) {
+    const readable = readableSessionCondition(filters.readableBy.userId, "events.taskId", {
+      nullable: true,
+    });
+    conditions.push(readable.sql);
+    params.push(...readable.params);
+  }
+
   if (filters.category) {
     conditions.push("category = ?");
     params.push(filters.category);

package/src/be/migrations/230_session_shares.sql

@@ -0,0 +1,23 @@
+-- Session sharing. A session is a root task (parentTaskId IS NULL) plus its
+-- descendants. A root with no active row stays private to its owner
+-- (agent_tasks.requestedByUserId); a root with no owner stays open to all.
+--
+-- Rows are never deleted: revoking sets revokedAt/revokedBy, and an access
+-- change revokes the active row and inserts a new one in one transaction, so
+-- every row for a root is its share history. userId NULL means everyone.
+CREATE TABLE session_shares (
+  id TEXT PRIMARY KEY,
+  rootTaskId TEXT NOT NULL REFERENCES agent_tasks(id) ON DELETE CASCADE,
+  userId TEXT REFERENCES users(id),
+  access TEXT NOT NULL CHECK (access IN ('read', 'write')),
+  createdAt TEXT NOT NULL,
+  revokedAt TEXT,
+  revokedBy TEXT REFERENCES users(id),
+  created_by TEXT REFERENCES users(id),
+  updated_by TEXT REFERENCES users(id)
+);
+
+-- At most one active row per (root, target); revoked rows pile up beside it.
+CREATE UNIQUE INDEX session_shares_active
+  ON session_shares(rootTaskId, COALESCE(userId, '*')) WHERE revokedAt IS NULL;
+CREATE INDEX session_shares_user ON session_shares(userId) WHERE revokedAt IS NULL;

package/src/be/rbac-roles.ts

@@ -35,6 +35,8 @@ export const BUILTIN_ROLES = [
       "task.action.own",
       "task.fs.mutate",
       "favorite.write.own",
+      "session.share",
+      "session.presence",
     ],
   },
 ] satisfies (BuiltinRoleDefinition & { isBuiltin: true })[];