@desplega.ai/agent-swarm 2.3.0 → 2.4.1

package/src/ranking/telemetry-ranking.ts

@@ -0,0 +1,119 @@
+/**
+ * The `telemetry_ranking` listing: what an install opted into the public ranking
+ * shows on agent-swarm.dev/ranking. Stored stringified in the global
+ * `swarm_config` key `telemetry_ranking` and sent as the `listing` property of
+ * `ranking.opted_in`.
+ *
+ * The proxy owns the contract (`src/telemetry-contract/ranking/`, vendored by
+ * `bun run sync:telemetry-contract`). This schema and the proxy's Go decoder are
+ * both held to its fixtures. Pure: imported by the API and the dashboard.
+ */
+import { z } from "zod";
+import { RANKING_TAXONOMY } from "../telemetry-contract/ranking-taxonomy.gen";
+import type { OrgIdentityStatus } from "../utils/org-identity";
+import { normalizeOrgWebsite } from "../utils/org-website";
+
+export { RANKING_TAXONOMY };
+
+export const TELEMETRY_RANKING_KEY = "telemetry_ranking";
+export const PUBLIC_RANKING_ENABLED_KEY = "PUBLIC_RANKING_ENABLED";
+export const TELEMETRY_RANKING_MAX_BYTES = 2048;
+
+export const RANKING_CATEGORIES = Object.keys(RANKING_TAXONOMY) as [
+  keyof typeof RANKING_TAXONOMY,
+  ...(keyof typeof RANKING_TAXONOMY)[],
+];
+const hostname = z.string().refine((v) => normalizeOrgWebsite(v) === v, "bare hostname");
+const nullableText = (max: number) => z.string().trim().min(1).max(max).nullable();
+
+function inCategory(category: string, subcategory: string | null): boolean {
+  if (subcategory === null) return true;
+  const subs: readonly string[] = RANKING_TAXONOMY[category as keyof typeof RANKING_TAXONOMY];
+  return subs?.includes(subcategory) ?? false;
+}
+
+export const telemetryRankingV1 = z
+  .strictObject({
+    v: z.literal(1),
+    /** Minted by v2.4.0 for the retired ranking PR. Still parsed, never written; the proxy ignores it. */
+    claim: z
+      .string()
+      .regex(/^rk_[0-9a-f]{32}$/)
+      .optional(),
+    name: z.string().trim().min(1).max(60),
+    domain: hostname,
+    category: z.enum(RANKING_CATEGORIES),
+    subcategory: z
+      .string()
+      .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+      .max(40)
+      .nullable(),
+    description: nullableText(160),
+    sourceCodeUrl: z
+      .url({ protocol: /^https$/ })
+      .max(200)
+      .nullable(),
+    updatedAt: z.iso.datetime(),
+  })
+  .refine((l) => inCategory(l.category, l.subcategory), {
+    path: ["subcategory"],
+    message: "not in this category",
+  });
+
+/** Discriminated on `v`; a v2 is added here, never by editing v1. */
+export const telemetryRankingSchema = z.discriminatedUnion("v", [telemetryRankingV1]);
+export type TelemetryRanking = z.infer<typeof telemetryRankingSchema>;
+
+export function parseTelemetryRanking(raw: string): TelemetryRanking {
+  if (new TextEncoder().encode(raw).length > TELEMETRY_RANKING_MAX_BYTES) {
+    throw new Error(`telemetry_ranking exceeds ${TELEMETRY_RANKING_MAX_BYTES} bytes`);
+  }
+  return telemetryRankingSchema.parse(JSON.parse(raw));
+}
+
+/** The stored listing, or null when it is missing or no longer valid. */
+export function readTelemetryRanking(raw: string | null | undefined): TelemetryRanking | null {
+  if (!raw?.trim()) return null;
+  try {
+    return parseTelemetryRanking(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** What the admin picks in the ranking form. Name and domain are never typed here. */
+export const rankingFormSchema = z.object({
+  category: z.enum(RANKING_CATEGORIES),
+  subcategory: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  sourceCodeUrl: z.string().nullable().optional(),
+});
+export type RankingForm = z.infer<typeof rankingFormSchema>;
+
+const blankToNull = (value: string | null | undefined) => value?.trim() || null;
+
+/**
+ * Build and validate the listing. Name and domain are copied from the org
+ * identity (`SWARM_ORG_NAME`, `SWARM_ORG_WEBSITE`); throws when the identity is
+ * not set or a form field breaks the contract.
+ */
+export function buildListing(
+  identity: OrgIdentityStatus,
+  form: RankingForm,
+  now: Date = new Date(),
+): TelemetryRanking {
+  if (!identity.ok || !identity.name || !identity.website) {
+    throw new Error(`Org identity is missing: ${identity.missing.join(", ")}`);
+  }
+  const listing = {
+    v: 1 as const,
+    name: identity.name,
+    domain: identity.website,
+    category: form.category,
+    subcategory: blankToNull(form.subcategory),
+    description: blankToNull(form.description),
+    sourceCodeUrl: blankToNull(form.sourceCodeUrl),
+    updatedAt: now.toISOString(),
+  };
+  return parseTelemetryRanking(JSON.stringify(listing));
+}

package/src/ranking/usage.ts

@@ -0,0 +1,57 @@
+/**
+ * Worker side of the public ranking: the `ranking.usage` properties for one
+ * session. Pure, so the runner and its test share the gate.
+ */
+import { isEnvFlagEnabled } from "../utils/env-flag";
+import { orgIdentityStatus } from "../utils/org-identity";
+
+export interface SessionTokens {
+  inputTokens?: number | null;
+  outputTokens?: number | null;
+  cacheReadTokens?: number | null;
+  cacheWriteTokens?: number | null;
+}
+
+export interface RankingUsageProps {
+  /** The same model and provider `session.cost` reports for the session. */
+  model: string;
+  provider: string;
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+const tokens = (value: number | null | undefined) =>
+  typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+
+/**
+ * Null unless telemetry is on, `PUBLIC_RANKING_ENABLED` is set and both org
+ * identity envs are set. Carries token counts plus the model and provider
+ * (for the per-model chart), never the task, agent or cost.
+ */
+export function rankingUsageProps(
+  cost: SessionTokens,
+  session: { model: string; provider: string },
+  env: NodeJS.ProcessEnv = process.env,
+): RankingUsageProps | null {
+  if (!isEnvFlagEnabled("ANONYMIZED_TELEMETRY", true, env)) return null;
+  if (!isEnvFlagEnabled("PUBLIC_RANKING_ENABLED", false, env)) return null;
+  const identity = { SWARM_ORG_NAME: env.SWARM_ORG_NAME, SWARM_ORG_WEBSITE: env.SWARM_ORG_WEBSITE };
+  if (!orgIdentityStatus(identity).ok) return null;
+  const input = tokens(cost.inputTokens);
+  const output = tokens(cost.outputTokens);
+  const cacheRead = tokens(cost.cacheReadTokens);
+  const cacheWrite = tokens(cost.cacheWriteTokens);
+  return {
+    model: session.model,
+    provider: session.provider,
+    // The unified sum, as computeContextUsedUnified counts it.
+    totalTokens: input + cacheRead + cacheWrite + output,
+    inputTokens: input,
+    outputTokens: output,
+    ...(cost.cacheReadTokens != null ? { cacheReadTokens: cacheRead } : {}),
+    ...(cost.cacheWriteTokens != null ? { cacheWriteTokens: cacheWrite } : {}),
+  };
+}

package/src/rbac/admission.ts

@@ -8,7 +8,20 @@ export type AdmissionGrant = {
   };
 };
 
-export type AdmissionRbac = { permission: PermissionVerb } | { ungated: string };
+/**
+ * `alsoAdmits` names verbs that admit the route as well as `permission`, for a
+ * route that serves two features (each handler check still names its own verb).
+ */
+export type AdmissionRbac =
+  | { permission: PermissionVerb; alsoAdmits?: readonly PermissionVerb[] }
+  | { ungated: string };
+
+function grantedVerb(
+  rbac: { permission: PermissionVerb; alsoAdmits?: readonly PermissionVerb[] },
+  grant: AdmissionGrant,
+): PermissionVerb | undefined {
+  return [rbac.permission, ...(rbac.alsoAdmits ?? [])].find((verb) => grant.verbs.has(verb));
+}
 
 export type AdmissionDecision =
   | { allow: true; verb?: PermissionVerb }
@@ -29,10 +42,11 @@ export function decideAdmission(input: {
   }
 
   if (input.rbac && "permission" in input.rbac) {
-    const verb = input.rbac.permission;
-    if (input.grant.verbs.has(verb)) {
-      return { allow: true, verb };
+    const granted = grantedVerb(input.rbac, input.grant);
+    if (granted) {
+      return { allow: true, verb: granted };
     }
+    const verb = input.rbac.permission;
     return { allow: false, reason: `admission: missing permission '${verb}'`, verb };
   }
 
@@ -54,10 +68,11 @@ export function decideToolAdmission(input: {
   }
 
   if (input.rbac && "permission" in input.rbac) {
-    const verb = input.rbac.permission;
-    if (input.grant.verbs.has(verb)) {
-      return { allow: true, verb };
+    const granted = grantedVerb(input.rbac, input.grant);
+    if (granted) {
+      return { allow: true, verb: granted };
     }
+    const verb = input.rbac.permission;
     return { allow: false, reason: `admission: missing permission '${verb}'`, verb };
   }
 

package/src/rbac/legacy-policy.ts

@@ -285,6 +285,8 @@ export const LEGACY_POLICY = {
   "task.action.own": requesterOwnsTask,
   "task.fs.mutate": taskFsMutate,
   "task.parent.attach": taskFsMutate,
+  "session.share": operatorOrUser,
+  "session.presence": operatorOrUser,
   "task.progress.write": taskProgressWrite,
   "favorite.write.own": anyAuthenticated,
   "memory.learning.inject": leadOnly,

package/src/rbac/permissions.ts

@@ -89,6 +89,15 @@ export const PERMISSIONS = {
       "Write a task's progress, status, or output (its assignee, a lead, a human, or anyone while unassigned).",
     namespace: "task",
   },
+  "session.share": {
+    description:
+      "Change who can view or edit a session the principal owns (the owner check runs in the handler).",
+    namespace: "task",
+  },
+  "session.presence": {
+    description: "Join the presence room of a session the principal can view.",
+    namespace: "task",
+  },
   "favorite.write.own": {
     description: "Set a favorite the caller owns.",
     namespace: "favorite",

package/src/realtime/auth.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage } from "node:http";
 import { getAgentById, getTaskById } from "../be/db";
 import { getUserGrant } from "../be/rbac-roles";
+import { getSessionRoot, sessionAccessForRoot } from "../be/session-shares";
 import { getCombConfig } from "../comb/config";
 import { mcpOverflowAuthError } from "../kv-overflow";
 import { reservedNamespaceError } from "../kv-reserved-namespaces";
@@ -19,6 +20,8 @@ export type RoomAuthorizationInfo = RoomNamespaceInfo & {
   callOrigin?: "http" | "mcp" | "ws";
   userId?: string;
   isOperator?: boolean;
+  /** The user an operator-key dashboard tab picked (`X-Swarm-User-Id`), captured on its ticket. */
+  dashboardUserId?: string;
 };
 
 export type ResolvedRoomNamespace = {
@@ -39,6 +42,7 @@ export type RoomNamespaceOperation =
 
 const COMB_PRESENCE_NAMESPACE = /^presence:comb:[A-Za-z0-9_-]{1,64}:[A-Za-z0-9_-]{1,64}$/;
 const COMB_PRESENCE_OPERATIONS = new Set<RoomNamespaceOperation>(["join", "leave", "presence"]);
+const SESSION_PRESENCE_NAMESPACE = /^presence:session:([A-Za-z0-9_-]{1,64})$/;
 
 function pageNamespace(pageId: string): string | null {
   try {
@@ -162,6 +166,10 @@ export async function authorizeRoomNamespace(
     return null;
   }
 
+  if (namespace.startsWith("presence:session:")) {
+    return authorizeSessionPresence(namespace, info, access);
+  }
+
   const reservedError = reservedNamespaceError(namespace);
   if (reservedError) return reservedError;
 
@@ -203,3 +211,64 @@ export async function authorizeRoomNamespace(
 
   return null;
 }
+
+/**
+ * Bus topic published after a session's shares change. Sockets in that
+ * session's presence room re-check access and are evicted when it ended.
+ */
+export function sessionAccessTopic(rootTaskId: string): string {
+  return `session-access:${rootTaskId}`;
+}
+
+/** The root task id of a `presence:session:<rootTaskId>` namespace, else undefined. */
+export function sessionPresenceRoot(namespace: string): string | undefined {
+  return SESSION_PRESENCE_NAMESPACE.exec(namespace)?.[1];
+}
+
+/**
+ * `presence:session:<rootTaskId>`: who is viewing (and typing in) a session.
+ * Presence-only, dashboard-only, and gated on read access so it never reveals
+ * who is inside a private session. An operator-key tab with no picked user
+ * keeps the access it has everywhere else.
+ */
+async function authorizeSessionPresence(
+  namespace: string,
+  info: RoomAuthorizationInfo,
+  access: boolean | RoomNamespaceOperation,
+): Promise<string | null> {
+  const match = SESSION_PRESENCE_NAMESPACE.exec(namespace);
+  if (!match) return "invalid session presence namespace";
+  if (info.pageId || info.agentId || (!info.isOperator && !info.userId)) {
+    return "Session presence requires dashboard authentication";
+  }
+  if (typeof access !== "string" || !COMB_PRESENCE_OPERATIONS.has(access)) {
+    return "Session presence rooms only allow join, leave, and presence";
+  }
+  const principal = info.isOperator
+    ? ({ kind: "operator" } as const)
+    : ({ kind: "user", userId: info.userId! } as const);
+  if (
+    !can({
+      principal,
+      verb: "session.presence",
+      resource: { kind: "kv-namespace", namespace },
+      source: info.callOrigin === "mcp" ? "mcp" : "http",
+    }).allow
+  ) {
+    return "Session presence requires the session.presence permission";
+  }
+  if (info.userId && isRbacEnabled()) {
+    const grant = await getUserGrant(info.userId);
+    if (!grant.grantsAll && !grant.verbs.has("session.presence")) {
+      return "Session presence requires the session.presence permission";
+    }
+  }
+  const viewerId = info.isOperator ? info.dashboardUserId : info.userId;
+  if (info.isOperator && !viewerId) return null;
+  const root = await getSessionRoot(match[1]!);
+  if (!root || root.id !== match[1]) return "session not found";
+  if ((await sessionAccessForRoot(viewerId ?? null, root)) === "none") {
+    return "You don't have access to this session";
+  }
+  return null;
+}

package/src/realtime/tickets.ts

@@ -3,7 +3,10 @@ import type { HttpRequestAuth } from "../utils/request-auth-context";
 export const REALTIME_TICKET_TTL_MS = 60_000;
 export const REALTIME_TICKET_CAPACITY = 10_000;
 
-export type RealtimeTicketAuth = Extract<HttpRequestAuth, { kind: "operator" | "user" }>;
+export type RealtimeTicketAuth = Extract<HttpRequestAuth, { kind: "operator" | "user" }> & {
+  /** The user an operator-key dashboard tab picked (`X-Swarm-User-Id`), for session presence. */
+  dashboardUserId?: string;
+};
 
 type StoredTicket = {
   auth: RealtimeTicketAuth;

package/src/realtime/transport.ts

@@ -10,7 +10,12 @@ import { extractAndVerifyCookie } from "../utils/page-session";
 import type { HttpRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { registerSessionTokenConnection } from "../utils/session-token-connections";
-import { authorizeRoomNamespace, resolveRoomNamespace } from "./auth";
+import {
+  authorizeRoomNamespace,
+  resolveRoomNamespace,
+  sessionAccessTopic,
+  sessionPresenceRoot,
+} from "./auth";
 import { realtimeBus } from "./bus";
 import {
   addWorkerSubscription,
@@ -64,6 +69,7 @@ type Identity = {
   pageId?: string;
   userId?: string;
   isOperator?: boolean;
+  dashboardUserId?: string;
 };
 type Viewer = { userId: string; name: string; kind: "user" | "guest" | "agent" };
 type AuthenticatedConnection = {
@@ -81,7 +87,7 @@ function header(req: IncomingMessage, name: string): string | undefined {
 
 function identityFromHttpAuth(
   req: IncomingMessage,
-  auth: HttpRequestAuth,
+  auth: HttpRequestAuth & { dashboardUserId?: string },
 ): AuthenticatedConnection {
   if (auth.kind === "controller") throw new Error("Controller tokens cannot use realtime");
   if (auth.kind === "agent") {
@@ -110,6 +116,7 @@ function identityFromHttpAuth(
         auth.kind === "agent" ? (auth.taskId ?? undefined) : header(req, "x-source-task-id"),
       userId: auth.kind === "user" ? auth.userId : undefined,
       isOperator: auth.kind === "operator",
+      dashboardUserId: auth.kind === "operator" ? auth.dashboardUserId : undefined,
     } satisfies Identity,
     me: {
       userId: auth.kind === "user" ? auth.userId : (agentId ?? guestId),
@@ -228,7 +235,12 @@ function connect(
       )
     : undefined;
   void auth.sessionToken?.check().catch(() => ws.close(1008, "Session token revoked or expired"));
-  const rooms = new Map<string, { room: LiveRoom; version: number; stop: () => void }>();
+  // `suspended`: a session presence room whose access is being re-checked
+  // after a share change; nothing is forwarded until the check passes.
+  const rooms = new Map<
+    string,
+    { room: LiveRoom; version: number; stop: () => void; suspended?: boolean }
+  >();
   const channels = new Map<string, () => void>();
   const pending = new Map<number, number>();
   const clientId = crypto.getRandomValues(new Uint32Array(1))[0]!;
@@ -313,6 +325,9 @@ function connect(
       if (namespace.startsWith("presence:comb:") && msg.name !== "default") {
         throw new Error("Comb presence uses the default room");
       }
+      if (namespace.startsWith("presence:session:") && msg.name !== "default") {
+        throw new Error("Session presence uses the default room");
+      }
       const denied = await authorizeRoomNamespace(namespace, auth.identity, msg.op, msg.name);
       if (denied) throw new Error(typeof denied === "string" ? denied : "Forbidden");
       if (closed) return;
@@ -352,12 +367,14 @@ function connect(
             room = await getRoom(namespace, msg.name, msg.schemaVersion, { create: false });
           } catch (error) {
             if (!(error instanceof Error) || error.message !== "room does not exist") throw error;
-            // Creating a room is a write. Comb presence rooms take only presence
-            // operations, so they check creation as a join.
+            // Creating a room is a write. Comb and session presence rooms take
+            // only presence operations, so they check creation as a join.
             const creationDenied = await authorizeRoomNamespace(
               namespace,
               auth.identity,
-              namespace.startsWith("presence:comb:") ? "join" : true,
+              namespace.startsWith("presence:comb:") || namespace.startsWith("presence:session:")
+                ? "join"
+                : true,
             );
             if (creationDenied) throw new Error(creationDenied);
             if (closed) return;
@@ -365,6 +382,7 @@ function connect(
           }
           if (closed) return;
           const stopRoom = realtimeBus.subscribe(key, (event) => {
+            if (rooms.get(key)?.suspended) return;
             const view = event as ReturnType<typeof roomView> & { type: string };
             const type = view.type;
             if (type === "deleted") {
@@ -387,17 +405,67 @@ function connect(
                 .catch(() => ws.close(1011, "Room reset failed"));
             }
           });
-          const stopPresence = realtimeBus.subscribe(`presence:${key}`, (peers) =>
-            send({ type: "presence", name: msg.name, namespace, peers }),
-          );
+          const stopPresence = realtimeBus.subscribe(`presence:${key}`, (peers) => {
+            if (rooms.get(key)?.suspended) return;
+            send({ type: "presence", name: msg.name, namespace, peers });
+          });
+          const sessionRoot = sessionPresenceRoot(namespace);
+          let accessCheck = 0;
+          // A share change can end this viewer's read access: stop forwarding
+          // at once, then evict, or resume if access remains.
+          const stopAccess = sessionRoot
+            ? realtimeBus.subscribe(sessionAccessTopic(sessionRoot), () => {
+                const joined = rooms.get(key);
+                if (!joined) return;
+                joined.suspended = true;
+                const check = ++accessCheck;
+                void authorizeRoomNamespace(namespace, auth.identity, "join")
+                  .catch(() => "Session access check failed")
+                  .then((denied) => {
+                    const current = rooms.get(key);
+                    if (closed || !current || check !== accessCheck) return;
+                    if (denied) {
+                      leave(key);
+                      send({ type: "error", name: msg.name, namespace, error: denied });
+                      return;
+                    }
+                    current.suspended = false;
+                    send({
+                      type: "presence",
+                      name: msg.name,
+                      namespace,
+                      peers: [...current.room.awareness.getStates().values()],
+                    });
+                  });
+              })
+            : undefined;
           rooms.set(key, {
             room,
             version: msg.schemaVersion,
             stop: () => {
               stopRoom();
               stopPresence();
+              stopAccess?.();
             },
+            suspended: sessionRoot !== undefined,
           });
+          if (sessionRoot) {
+            // A share change published while the room loaded reached no
+            // subscriber, so check again now that the access subscriber is
+            // live. Anything later is that subscriber's to handle.
+            const check = ++accessCheck;
+            const denied = await authorizeRoomNamespace(namespace, auth.identity, "join").catch(
+              () => "Session access check failed",
+            );
+            if (closed) return;
+            if (denied) {
+              leave(key);
+              throw new Error(denied);
+            }
+            const current = rooms.get(key);
+            if (!current) throw new Error("You don't have access to this session");
+            if (check === accessCheck) current.suspended = false;
+          }
           room.awareness.states.set(clientId, { ...auth.me, data: {} });
           room.awareness.meta.set(clientId, { clock: 1, lastUpdated: Date.now() });
           publishPresence(room);

package/src/scripts-runtime/sdk-allowlist.ts

@@ -180,6 +180,13 @@ export const SDK_TOOL_NAME_MAP = {
   app_list: "app-list",
   app_patch: "app-patch",
   app_query: "app-query",
+  app_rows_list: "app-rows-list",
+  app_row_get: "app-row-get",
+  app_row_create: "app-row-create",
+  app_rows_create: "app-rows-create",
+  app_row_patch: "app-row-patch",
+  app_row_delete: "app-row-delete",
+  app_rows_delete: "app-rows-delete",
   app_rollback: "app-rollback",
   app_sync: "app-sync",
   app_upsert: "app-upsert",

package/src/scripts-runtime/types/stdlib.d.ts

@@ -658,6 +658,37 @@ declare module "swarm-sdk" {
       query: string;
       params?: Record<string, string | number | boolean>;
     }): Promise<unknown>;
+    app_rows_list(args: {
+      appId: string;
+      model: string;
+      equals?: Record<string, string | number | boolean>;
+      sort?: `${string}:asc` | `${string}:desc`;
+      limit?: number;
+    }): Promise<unknown>;
+    app_row_get(args: { appId: string; model: string; rowId: string }): Promise<unknown>;
+    app_row_create(args: {
+      appId: string;
+      model: string;
+      values: Record<string, unknown>;
+    }): Promise<unknown>;
+    app_rows_create(args: {
+      appId: string;
+      model: string;
+      rows: Record<string, unknown>[];
+    }): Promise<unknown>;
+    app_row_patch(args: {
+      appId: string;
+      model: string;
+      rowId: string;
+      values: Record<string, unknown>;
+    }): Promise<unknown>;
+    app_row_delete(args: { appId: string; model: string; rowId: string }): Promise<unknown>;
+    app_rows_delete(args: {
+      appId: string;
+      model: string;
+      equals: Record<string, string | number | boolean>;
+      limit?: number;
+    }): Promise<unknown>;
     app_rollback(args: {
       appId: string;
       version: number;

package/src/scripts-runtime/types/swarm-sdk.d.ts

@@ -640,6 +640,37 @@ declare module "swarm-sdk" {
       query: string;
       params?: Record<string, string | number | boolean>;
     }): Promise<unknown>;
+    app_rows_list(args: {
+      appId: string;
+      model: string;
+      equals?: Record<string, string | number | boolean>;
+      sort?: `${string}:asc` | `${string}:desc`;
+      limit?: number;
+    }): Promise<unknown>;
+    app_row_get(args: { appId: string; model: string; rowId: string }): Promise<unknown>;
+    app_row_create(args: {
+      appId: string;
+      model: string;
+      values: Record<string, unknown>;
+    }): Promise<unknown>;
+    app_rows_create(args: {
+      appId: string;
+      model: string;
+      rows: Record<string, unknown>[];
+    }): Promise<unknown>;
+    app_row_patch(args: {
+      appId: string;
+      model: string;
+      rowId: string;
+      values: Record<string, unknown>;
+    }): Promise<unknown>;
+    app_row_delete(args: { appId: string; model: string; rowId: string }): Promise<unknown>;
+    app_rows_delete(args: {
+      appId: string;
+      model: string;
+      equals: Record<string, string | number | boolean>;
+      limit?: number;
+    }): Promise<unknown>;
     app_rollback(args: {
       appId: string;
       version: number;

package/src/server.ts

@@ -11,6 +11,7 @@ import { resolveTemplate } from "./prompts/resolver";
 import { isRbacEnabled } from "./rbac";
 import { getSlackConfiguration } from "./slack/config";
 import { registerAcceptSteerTool } from "./tools/accept-steer";
+import { registerAppActionRunTool } from "./tools/app-action-run";
 import { registerAppDiffTool } from "./tools/app-diff";
 import { registerAppGetTool } from "./tools/app-get";
 import { registerAppHistoryTool } from "./tools/app-history";
@@ -18,6 +19,7 @@ import { registerAppListTool } from "./tools/app-list";
 import { registerAppPatchTool } from "./tools/app-patch";
 import { registerAppQueryTool } from "./tools/app-query";
 import { registerAppRollbackTool } from "./tools/app-rollback";
+import { registerAppRowTools } from "./tools/app-rows";
 import { registerAppSyncTool } from "./tools/app-sync";
 import { registerAppUpsertTool } from "./tools/app-upsert";
 import { registerCancelApprovalRequestTool } from "./tools/cancel-approval-request";
@@ -643,6 +645,8 @@ export async function createServer(
   // Pages capability - DB-backed lightweight artifacts (HTML / JSON specs).
   if (hasCapability("pages")) {
     registerAppGetTool(server);
+    registerAppRowTools(server);
+    registerAppActionRunTool(server);
     registerAppHistoryTool(server);
     registerAppDiffTool(server);
     registerAppListTool(server);

package/src/slack/blocks.ts

@@ -97,6 +97,10 @@ export function splitSlackSectionText(text: string): string[] {
     if (splitIdx < MAX_SECTION_LENGTH / 2) {
       // No good break point at all, hard split
       splitIdx = MAX_SECTION_LENGTH;
+      // Keep a surrogate pair (emoji, astral char) together: never end a
+      // chunk on a lone high surrogate.
+      const prev = remaining.charCodeAt(splitIdx - 1);
+      if (prev >= 0xd800 && prev <= 0xdbff) splitIdx -= 1;
     }
     chunks.push(remaining.slice(0, splitIdx));
     remaining = remaining.slice(splitIdx).trimStart();
@@ -104,6 +108,20 @@ export function splitSlackSectionText(text: string): string[] {
   return chunks;
 }
 
+// Slack's hard cap on section text.
+const SLACK_SECTION_TEXT_LIMIT = 3000;
+
+/**
+ * Default blocks for a tool message sent without explicit `blocks`: one
+ * mrkdwn section per chunk, so text over the section limit still sends.
+ * Text Slack accepts in one section stays one section, so links and code
+ * fences are never split below the limit.
+ */
+export function buildMrkdwnSectionBlocks(text: string): SlackBlock[] {
+  if (text.length <= SLACK_SECTION_TEXT_LIMIT) return [sectionBlock(text)];
+  return splitSlackSectionText(text).map((chunk) => sectionBlock(chunk));
+}
+
 // --- Block primitives ---
 
 function contextBlock(...elements: string[]): SlackBlock {