@desplega.ai/agent-swarm 2.2.0 → 2.4.0

package/src/tests/slack-update.test.ts

@@ -128,6 +128,61 @@ describe("slack-update", () => {
     });
   });
 
+  test("splits a long message into sections under Slack's cap", async () => {
+    const message = Array.from(
+      { length: 120 },
+      (_, index) => `line ${String(index).padStart(3, "0")} radar item with some words`,
+    )
+      .join("\n")
+      .slice(0, 3946);
+    const tool = buildTool();
+    const result = await tool.handler(
+      { channelId: "C1", messageTs: "1783411554.596189", message },
+      meta(leadAgentId),
+    );
+
+    expect(result.structuredContent.success).toBe(true);
+    const payload = mockChatUpdate.mock.calls[0][0] as {
+      text: string;
+      blocks: { type: string; text: { type: string; text: string } }[];
+    };
+    expect(payload.text).toBe(message);
+    expect(payload.blocks.length).toBeGreaterThanOrEqual(2);
+    for (const block of payload.blocks) {
+      expect(block.type).toBe("section");
+      expect(block.text.text.length).toBeLessThanOrEqual(2900);
+    }
+    const joined = payload.blocks.map((block) => block.text.text).join("");
+    expect(joined.replace(/\s/g, "")).toBe(message.replace(/\s/g, ""));
+  });
+
+  test("keeps a 2,931-char message with an emoji at 2,900 in one intact section", async () => {
+    const message = `${"x".repeat(2899)}😀${"y".repeat(30)}`;
+    expect(message.length).toBe(2931);
+    const tool = buildTool();
+    const result = await tool.handler(
+      { channelId: "C1", messageTs: "1783411554.596189", message },
+      meta(leadAgentId),
+    );
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(mockChatUpdate.mock.calls[0][0].blocks).toEqual([
+      { type: "section", text: { type: "mrkdwn", text: message } },
+    ]);
+  });
+
+  test("keeps a short message in exactly one section", async () => {
+    const tool = buildTool();
+    await tool.handler(
+      { channelId: "C1", messageTs: "1783411554.596189", message: "short" },
+      meta(leadAgentId),
+    );
+
+    expect(mockChatUpdate.mock.calls[0][0]).toMatchObject({
+      blocks: [{ type: "section", text: { type: "mrkdwn", text: "short" } }],
+    });
+  });
+
   test.each([
     ["message_not_found", "No message found at that timestamp in this channel."],
     [

package/src/tests/slack-user-dm.test.ts

@@ -0,0 +1,177 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { closeDb, createAgent, getSlackMessageByChannelTs, initDb } from "../be/db";
+import { isSlackUserId } from "../slack/dm";
+import { registerSlackPostTool } from "../tools/slack-post";
+import { registerSlackReadTool } from "../tools/slack-read";
+import { registerSlackStartThreadTool } from "../tools/slack-start-thread";
+
+const TEST_DB_PATH = "./test-slack-user-dm.sqlite";
+const USER_ID = "U08USERDM";
+// The bot's own IM with USER_ID: readable, writable, delivers message.im events.
+const BOT_DM = "D0BOTDM01";
+// Where Slack puts a bot post addressed to the bare user id: the bot is not a member.
+const FOREIGN_DM = "D0FOREIGN";
+
+function slackError(code: string): Error {
+  return Object.assign(new Error(`An API error occurred: ${code}`), {
+    data: { ok: false, error: code },
+  });
+}
+
+let tsCounter = 0;
+const postMessage = mock(async (args: { channel: string; thread_ts?: string }) => {
+  if (args.channel === FOREIGN_DM) throw slackError("channel_not_found");
+  const ts = `500.${++tsCounter}`;
+  return { ok: true, ts, channel: args.channel === USER_ID ? FOREIGN_DM : args.channel };
+});
+const conversationsOpen = mock(async (args: { users: string }) => {
+  if (args.users !== USER_ID) throw slackError("user_not_found");
+  return { ok: true, channel: { id: BOT_DM } };
+});
+const conversationsReplies = mock(async (args: { channel: string; ts: string }) => {
+  if (args.channel !== BOT_DM) throw slackError("channel_not_found");
+  return { ok: true, messages: [{ user: USER_ID, text: "reply from human", ts: args.ts }] };
+});
+
+mock.module("../slack/app", () => ({
+  getSlackApp: () => ({
+    client: {
+      chat: { postMessage },
+      conversations: { open: conversationsOpen, replies: conversationsReplies },
+      auth: { test: async () => ({ ok: true, user_id: "UBOT" }) },
+      users: { info: async () => ({ ok: true, user: { real_name: "Human" } }) },
+    },
+  }),
+}));
+
+type ToolResult = {
+  structuredContent: {
+    success: boolean;
+    message: string;
+    channelId?: string;
+    ts?: string;
+    messages?: Array<{ text: string }>;
+  };
+};
+type RegisteredTool = { handler: (args: unknown, extra: unknown) => Promise<ToolResult> };
+
+function buildTools() {
+  const server = new McpServer({ name: "slack-user-dm-test", version: "1.0.0" });
+  registerSlackPostTool(server);
+  registerSlackReadTool(server);
+  registerSlackStartThreadTool(server);
+  return (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+    ._registeredTools;
+}
+
+function meta(agentId: string) {
+  return { sessionId: "s1", requestInfo: { headers: { "x-agent-id": agentId } } };
+}
+
+async function removeDbFiles() {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+}
+
+let leadId: string;
+
+beforeAll(async () => {
+  await removeDbFiles();
+  initDb(TEST_DB_PATH);
+  leadId = (await createAgent({ name: "Lead DM", isLead: true, status: "idle" })).id;
+});
+
+beforeEach(() => {
+  postMessage.mockClear();
+  conversationsOpen.mockClear();
+  conversationsReplies.mockClear();
+});
+
+afterAll(async () => {
+  closeDb();
+  await removeDbFiles();
+});
+
+describe("Slack tools addressed with a user id", () => {
+  test("isSlackUserId matches user ids only", () => {
+    expect(isSlackUserId("U08NR6QD6CS")).toBe(true);
+    expect(isSlackUserId("W012ABCDEF")).toBe(true);
+    expect(isSlackUserId("D0A4T383FMF")).toBe(false);
+    expect(isSlackUserId("C0AR967K0KZ")).toBe(false);
+    expect(isSlackUserId("G01PRIVATE")).toBe(false);
+  });
+
+  test("slack-start-thread opens the bot DM and returns an id that reads and writes work on", async () => {
+    const tools = buildTools();
+
+    const started = await tools["slack-start-thread"]!.handler(
+      { channelId: USER_ID, message: "hello" },
+      meta(leadId),
+    );
+    expect(started.structuredContent.success).toBe(true);
+    expect(conversationsOpen).toHaveBeenCalledWith({ users: USER_ID });
+    expect(postMessage.mock.calls[0]![0].channel).toBe(BOT_DM);
+    expect(started.structuredContent.channelId).toBe(BOT_DM);
+    const threadTs = started.structuredContent.ts!;
+    // The recorded message points at the bot DM, so inbound replies match it.
+    expect((await getSlackMessageByChannelTs(BOT_DM, threadTs))?.threadTs).toBe(threadTs);
+
+    const posted = await tools["slack-post"]!.handler(
+      { channelId: BOT_DM, threadTs, message: "follow-up" },
+      meta(leadId),
+    );
+    expect(posted.structuredContent.success).toBe(true);
+    expect(postMessage.mock.calls[1]![0]).toMatchObject({ channel: BOT_DM, thread_ts: threadTs });
+
+    const read = await tools["slack-read"]!.handler({ channelId: BOT_DM, threadTs }, meta(leadId));
+    expect(read.structuredContent.success).toBe(true);
+    expect(read.structuredContent.messages?.[0]?.text).toContain("reply from human");
+  });
+
+  test("slack-post and slack-read with the user id resolve to the same bot DM", async () => {
+    const tools = buildTools();
+
+    const posted = await tools["slack-post"]!.handler(
+      { channelId: USER_ID, threadTs: "500.1", message: "by user id" },
+      meta(leadId),
+    );
+    expect(posted.structuredContent.success).toBe(true);
+    expect(postMessage.mock.calls[0]![0]).toMatchObject({ channel: BOT_DM, thread_ts: "500.1" });
+
+    const read = await tools["slack-read"]!.handler(
+      { channelId: USER_ID, threadTs: "500.1" },
+      meta(leadId),
+    );
+    expect(read.structuredContent.success).toBe(true);
+    expect(conversationsReplies.mock.calls[0]![0].channel).toBe(BOT_DM);
+  });
+
+  test("conversation ids pass through without opening a DM", async () => {
+    const tools = buildTools();
+
+    const started = await tools["slack-start-thread"]!.handler(
+      { channelId: "C0CHANNEL1", message: "channel post" },
+      meta(leadId),
+    );
+    expect(started.structuredContent.channelId).toBe("C0CHANNEL1");
+    expect(postMessage.mock.calls[0]![0].channel).toBe("C0CHANNEL1");
+    expect(conversationsOpen).not.toHaveBeenCalled();
+  });
+
+  test("a user id Slack cannot open a DM with fails without posting", async () => {
+    const tools = buildTools();
+
+    const started = await tools["slack-start-thread"]!.handler(
+      { channelId: "U0NOBODY1", message: "hello" },
+      meta(leadId),
+    );
+    expect(started.structuredContent.success).toBe(false);
+    expect(started.structuredContent.message).toContain("user_not_found");
+    expect(postMessage).not.toHaveBeenCalled();
+  });
+});

package/src/tests/used-by-route.test.ts

@@ -184,8 +184,18 @@ describe("POST /api/used-by", () => {
     await upsertSwarmConfig({ scope: "global", key: "SWARM_ORG_WEBSITE", value: "" });
     const result = await post({ granted: true }, OPERATOR);
     expect(result.statusCode).toBe(400);
+    expect(JSON.parse(result.body)).toEqual({
+      error: "Set the organization name and website first",
+    });
     expect(proxied).toEqual([]);
   });
+
+  test("a placeholder name still grants: the ranking's placeholder rule does not apply", async () => {
+    await upsertSwarmConfig({ scope: "global", key: "SWARM_ORG_NAME", value: "Swarm" });
+    const result = await post({ granted: true }, OPERATOR);
+    expect(result.statusCode).toBe(200);
+    expect(proxied[0]?.body).toMatchObject({ org_name: "Swarm", org_website: "acme.com" });
+  });
 });
 
 describe("fillOrgLogoFromWebsite", () => {

package/src/tools/slack-post.ts

@@ -8,8 +8,9 @@ import {
 } from "@/be/db";
 import { can } from "@/rbac";
 import { getSlackApp } from "@/slack/app";
-import { getTaskLink } from "@/slack/blocks";
+import { buildMrkdwnSectionBlocks, getTaskLink } from "@/slack/blocks";
 import { withAutoJoin } from "@/slack/channel-join";
+import { resolveSlackConversationId } from "@/slack/dm";
 import { externalChannelToolError, getChannelBlockReason } from "@/slack/external-channel";
 import { getAgentDisplayName, getAgentEmoji, markdownToSlack } from "@/slack/responses";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
@@ -24,7 +25,12 @@ export const registerSlackPostTool = (server: McpServer) => {
       annotations: { openWorldHint: true },
 
       inputSchema: z.object({
-        channelId: z.string().min(1).describe("The Slack channel ID to post to."),
+        channelId: z
+          .string()
+          .min(1)
+          .describe(
+            "The Slack channel ID to post to. A user ID (U…/W…) posts in the bot's DM with that user.",
+          ),
         message: z.string().min(1).max(4000).describe("The message content to post."),
         blocks: z
           .array(z.record(z.string(), z.unknown()))
@@ -42,7 +48,7 @@ export const registerSlackPostTool = (server: McpServer) => {
         messageTs: z.string().optional(),
       }),
     },
-    async ({ channelId, message, threadTs, blocks }, requestInfo, _meta) => {
+    async ({ channelId: requestedChannelId, message, threadTs, blocks }, requestInfo, _meta) => {
       if (!requestInfo.agentId) {
         return toolErr("Agent ID not found.");
       }
@@ -68,6 +74,14 @@ export const registerSlackPostTool = (server: McpServer) => {
         return toolErr("Slack not configured.");
       }
 
+      let channelId: string;
+      try {
+        channelId = await resolveSlackConversationId(app.client, requestedChannelId);
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return toolErr(`Failed to open a DM with ${requestedChannelId}: ${errorMsg}`);
+      }
+
       const blockReason = await getChannelBlockReason(app.client, channelId);
       if (blockReason) {
         return toolErr(externalChannelToolError(channelId, blockReason));
@@ -82,15 +96,7 @@ export const registerSlackPostTool = (server: McpServer) => {
         const contextKey = sourceTask?.contextKey;
         const tree = threadTs ? await getSlackTreeMessageByThread(channelId, threadTs) : null;
         const messageBlocks: Record<string, unknown>[] = [
-          ...(blocks ?? [
-            {
-              type: "section",
-              text: {
-                type: "mrkdwn",
-                text: slackMessage,
-              },
-            },
-          ]),
+          ...(blocks ?? buildMrkdwnSectionBlocks(slackMessage)),
         ];
         if (sourceTask && tree) {
           if (messageBlocks.length >= 50) {

package/src/tools/slack-read.ts

@@ -4,6 +4,7 @@ import { getAgentById, getInboxMessageById, getTaskById } from "@/be/db";
 import { can } from "@/rbac";
 import { getSlackApp } from "@/slack/app";
 import { withAutoJoin } from "@/slack/channel-join";
+import { resolveSlackConversationId } from "@/slack/dm";
 import { externalChannelToolError, getChannelBlockReason } from "@/slack/external-channel";
 import { downloadFile, type SlackFile } from "@/slack/files";
 import { attachableTask, attachSlackFilesForAgent } from "@/slack/inbound-files";
@@ -59,7 +60,9 @@ export const registerSlackReadTool = (server: McpServer) => {
         channelId: z
           .string()
           .optional()
-          .describe("Slack channel ID to read from (requires lead privileges)."),
+          .describe(
+            "Slack channel ID to read from (requires lead privileges). A user ID (U…/W…) reads the bot's DM with that user.",
+          ),
         threadTs: z
           .string()
           .optional()
@@ -155,6 +158,15 @@ export const registerSlackReadTool = (server: McpServer) => {
         return toolErr("Slack not configured.", { data: { messages: [] } });
       }
 
+      try {
+        slackChannelId = await resolveSlackConversationId(app.client, slackChannelId);
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return toolErr(`Failed to open a DM with ${slackChannelId}: ${errorMsg}`, {
+          data: { messages: [] },
+        });
+      }
+
       const blockReason = await getChannelBlockReason(app.client, slackChannelId);
       if (blockReason) {
         return toolErr(externalChannelToolError(slackChannelId, blockReason), {

package/src/tools/slack-reply.ts

@@ -11,7 +11,12 @@ import {
 } from "@/be/db";
 import { getTaskCitations } from "@/be/task-citations";
 import { getSlackApp } from "@/slack/app";
-import { buildCaptionBlock, getTaskLink, getTaskUrl } from "@/slack/blocks";
+import {
+  buildCaptionBlock,
+  buildMrkdwnSectionBlocks,
+  getTaskLink,
+  getTaskUrl,
+} from "@/slack/blocks";
 import { withAutoJoin } from "@/slack/channel-join";
 import { externalChannelToolError, getChannelBlockReason } from "@/slack/external-channel";
 import { getAgentDisplayName, getAgentEmoji, markdownToSlack } from "@/slack/responses";
@@ -140,15 +145,7 @@ export const registerSlackReplyTool = (server: McpServer) => {
 
         const tree = await getSlackTreeMessageByThread(slackChannelId, slackThreadTs);
         const messageBlocks: Record<string, unknown>[] = [
-          ...(renderedBlocks ?? [
-            {
-              type: "section",
-              text: {
-                type: "mrkdwn",
-                text: slackMessage,
-              },
-            },
-          ]),
+          ...(renderedBlocks ?? buildMrkdwnSectionBlocks(slackMessage)),
         ];
         for (const group of taskCitationSourceGroups(
           blocks ? JSON.stringify(blocks) : message,

package/src/tools/slack-start-thread.ts

@@ -3,7 +3,9 @@ import * as z from "zod";
 import { getAgentById, getTaskById, recordSlackMessage } from "@/be/db";
 import { can } from "@/rbac";
 import { getSlackApp } from "@/slack/app";
+import { buildMrkdwnSectionBlocks } from "@/slack/blocks";
 import { withAutoJoin } from "@/slack/channel-join";
+import { resolveSlackConversationId } from "@/slack/dm";
 import { externalChannelToolError, getChannelBlockReason } from "@/slack/external-channel";
 import { getAgentDisplayName, getAgentEmoji, markdownToSlack } from "@/slack/responses";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
@@ -18,7 +20,12 @@ export const registerSlackStartThreadTool = (server: McpServer) => {
       annotations: { openWorldHint: true },
 
       inputSchema: z.object({
-        channelId: z.string().min(1).describe("The Slack channel ID to post to."),
+        channelId: z
+          .string()
+          .min(1)
+          .describe(
+            "The Slack channel ID to post to. A user ID (U…/W…) opens the bot's DM with that user; use the returned channelId afterwards.",
+          ),
         message: z.string().min(1).max(4000).describe("The message content to post."),
         blocks: z
           .array(z.record(z.string(), z.unknown()))
@@ -32,7 +39,7 @@ export const registerSlackStartThreadTool = (server: McpServer) => {
         messageTs: z.string().optional(),
       }),
     },
-    async ({ channelId, message, blocks }, requestInfo, _meta) => {
+    async ({ channelId: requestedChannelId, message, blocks }, requestInfo, _meta) => {
       if (!requestInfo.agentId) {
         return toolErr("Agent ID not found.");
       }
@@ -57,6 +64,14 @@ export const registerSlackStartThreadTool = (server: McpServer) => {
         return toolErr("Slack not configured.");
       }
 
+      let channelId: string;
+      try {
+        channelId = await resolveSlackConversationId(app.client, requestedChannelId);
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return toolErr(`Failed to open a DM with ${requestedChannelId}: ${errorMsg}`);
+      }
+
       const blockReason = await getChannelBlockReason(app.client, channelId);
       if (blockReason) {
         return toolErr(externalChannelToolError(channelId, blockReason));
@@ -64,15 +79,7 @@ export const registerSlackStartThreadTool = (server: McpServer) => {
 
       try {
         const slackMessage = markdownToSlack(message);
-        const messageBlocks = blocks ?? [
-          {
-            type: "section",
-            text: {
-              type: "mrkdwn",
-              text: slackMessage,
-            },
-          },
-        ];
+        const messageBlocks = blocks ?? buildMrkdwnSectionBlocks(slackMessage);
 
         const result = await withAutoJoin(app.client, channelId, () =>
           app.client.chat.postMessage({

package/src/tools/slack-update.ts

@@ -4,6 +4,7 @@ import * as z from "zod";
 import { getAgentById } from "@/be/db";
 import { can } from "@/rbac";
 import { getSlackApp } from "@/slack/app";
+import { buildMrkdwnSectionBlocks } from "@/slack/blocks";
 import { externalChannelToolError, getChannelBlockReason } from "@/slack/external-channel";
 import { parseSlackTs } from "@/slack/message-text";
 import { markdownToSlack } from "@/slack/responses";
@@ -77,15 +78,7 @@ export const registerSlackUpdateTool = (server: McpServer) => {
           text: slackMessage,
           unfurl_links: false,
           unfurl_media: false,
-          blocks: [
-            {
-              type: "section",
-              text: {
-                type: "mrkdwn",
-                text: slackMessage,
-              },
-            },
-          ],
+          blocks: buildMrkdwnSectionBlocks(slackMessage),
         } satisfies ChatUpdatePayload;
         const result = await app.client.chat.update(updatePayload);
 

package/src/types.ts

@@ -453,6 +453,41 @@ export const ModelProfileSchema = z.object({
 });
 export type ModelProfile = z.infer<typeof ModelProfileSchema>;
 
+// ============================================================================
+// Session sharing
+// ============================================================================
+//
+// `SessionShareAccessSchema` MUST stay in sync with the SQL CHECK constraint
+// on session_shares.access (migration 230).
+
+export const SessionShareAccessSchema = z.enum(["read", "write"]);
+export type SessionShareAccess = z.infer<typeof SessionShareAccessSchema>;
+
+/** The caller's access to a session. `none` is never returned; it is a 403. */
+export const SessionAccessSchema = z.enum(["owner", "write", "read"]);
+
+export const SessionOwnerSchema = z
+  .object({ id: z.string(), name: z.string() })
+  .openapi("SessionOwner");
+
+export const SessionSharesSchema = z
+  .object({
+    /** What every user may do. `none` = private (owner and named users only). */
+    everyone: z.enum(["none", "read", "write"]),
+    users: z.array(
+      z.object({ userId: z.string(), access: SessionShareAccessSchema, createdAt: z.string() }),
+    ),
+  })
+  .openapi("SessionShares");
+export type SessionShares = z.infer<typeof SessionSharesSchema>;
+
+export const SessionSharesUpdateSchema = z.object({
+  everyone: z.enum(["none", "read", "write"]),
+  users: z
+    .array(z.object({ userId: z.string().min(1), access: SessionShareAccessSchema }))
+    .max(500),
+});
+
 // ============================================================================
 // Task Steering Messages
 // ============================================================================
@@ -1114,6 +1149,8 @@ export const InboxItemStateSchema = z
     doneAt: z.string().optional(),
     /** First-viewed timestamp, set once on first panel open. Independent of status. */
     readAt: z.string().optional(),
+    /** Read cursor: latest time the user marked the item read. Clients can set, move back, or clear it. Independent of readAt and status. */
+    lastReadAt: z.string().optional(),
     createdAt: z.string(),
     lastUpdatedAt: z.string(),
   })

package/src/utils/org-identity.ts

@@ -0,0 +1,33 @@
+/**
+ * The "is the org identity set" rule, shared by every feature that needs a real
+ * organization name and website (the public ranking, the "used by" grant).
+ * Pure: the API passes global config values, workers pass `process.env`.
+ */
+import { normalizeOrgWebsite } from "./org-website";
+
+export const ORG_IDENTITY_KEYS = ["SWARM_ORG_NAME", "SWARM_ORG_WEBSITE"] as const;
+export type OrgIdentityKey = (typeof ORG_IDENTITY_KEYS)[number];
+
+/** Names the product falls back to when none is set; they are not an org name. */
+const PLACEHOLDER_NAMES = new Set(["swarm", "your swarm"]);
+
+export interface OrgIdentityStatus {
+  /** The trimmed name, or null when blank. A placeholder is returned but listed as missing. */
+  name: string | null;
+  /** The website as a bare hostname, or null when blank or not a public hostname. */
+  website: string | null;
+  missing: OrgIdentityKey[];
+  ok: boolean;
+}
+
+export function orgIdentityStatus(src: {
+  SWARM_ORG_NAME?: string | null;
+  SWARM_ORG_WEBSITE?: string | null;
+}): OrgIdentityStatus {
+  const name = src.SWARM_ORG_NAME?.trim() || null;
+  const website = normalizeOrgWebsite(src.SWARM_ORG_WEBSITE) || null;
+  const missing: OrgIdentityKey[] = [];
+  if (!name || PLACEHOLDER_NAMES.has(name.toLowerCase())) missing.push("SWARM_ORG_NAME");
+  if (!website) missing.push("SWARM_ORG_WEBSITE");
+  return { name, website, missing, ok: missing.length === 0 };
+}

package/templates/skills/apps/SKILL.md

@@ -30,6 +30,23 @@ For every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch`
 
 One `app-get` returns everything needed to drive an app you did not write: `definition.queries` are runnable with `app-query` (supply every `$param` the query references), and `definition.actions` are invocable with `POST /api/apps/<id>/actions/<name>` (a `script` action runs its script, a `task` action spawns a task, a `sync` action refreshes sources). Read a query's `$param` placeholders and an action's kind/args from the definition before calling — do not guess parameter names.
 
+### Verified action caller
+
+Script actions receive `caller` as a reserved, server-stamped argument. The server overwrites `caller` from definition defaults and request input.
+
+```typescript
+type AppActionCaller = {
+  kind: "user" | "agent" | "operator" | "guest";
+  id: string | null;
+  name?: string;
+  pageId?: string;
+};
+```
+
+The caller identifies the authenticated user or agent. Operator and guest callers have `id: null`. A signed page session adds `pageId`.
+With the swarm key, a registered `X-Agent-ID` produces an agent caller and `agent:<id>` row provenance. Missing or unknown agent IDs remain operator callers.
+Task actions include the same caller as server-verified JSON in the task prompt. Script execution still uses the saved script owner's bindings.
+
 ## Safe schema evolution and rollback
 
 Prefer **hiding** a column over deleting it. A hidden column's values stay on every existing row, so an unhide or rollback can make it visible again. Hiding is metadata-only: hidden columns cannot be used in queries, page bindings, `app.mutate` values, or new row writes, and `required` is ignored while hidden. Row GETs still expose the historical value for backward compatibility.

package/templates/skills/apps/content.md

@@ -25,6 +25,23 @@ For every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch`
 
 One `app-get` returns everything needed to drive an app you did not write: `definition.queries` are runnable with `app-query` (supply every `$param` the query references), and `definition.actions` are invocable with `POST /api/apps/<id>/actions/<name>` (a `script` action runs its script, a `task` action spawns a task, a `sync` action refreshes sources). Read a query's `$param` placeholders and an action's kind/args from the definition before calling — do not guess parameter names.
 
+### Verified action caller
+
+Script actions receive `caller` as a reserved, server-stamped argument. The server overwrites `caller` from definition defaults and request input.
+
+```typescript
+type AppActionCaller = {
+  kind: "user" | "agent" | "operator" | "guest";
+  id: string | null;
+  name?: string;
+  pageId?: string;
+};
+```
+
+The caller identifies the authenticated user or agent. Operator and guest callers have `id: null`. A signed page session adds `pageId`.
+With the swarm key, a registered `X-Agent-ID` produces an agent caller and `agent:<id>` row provenance. Missing or unknown agent IDs remain operator callers.
+Task actions include the same caller as server-verified JSON in the task prompt. Script execution still uses the saved script owner's bindings.
+
 ## Safe schema evolution and rollback
 
 Prefer **hiding** a column over deleting it. A hidden column's values stay on every existing row, so an unhide or rollback can make it visible again. Hiding is metadata-only: hidden columns cannot be used in queries, page bindings, `app.mutate` values, or new row writes, and `required` is ignored while hidden. Row GETs still expose the historical value for backward compatibility.

package/templates/skills/code-quality/content.md

@@ -43,7 +43,7 @@ The Repository Guidelines carry `allowMerge` and `mergeChecks`.
 1. Read `/review/rules.md` on the shared agent-fs drive. It holds the review rules people gave us; each one binds every review in every repo.
 2. Read the repo's `REVIEW.md` when it has one. It holds the repo-specific checks.
 3. Set the effort from the PR body's `Risk:` line. `low`: a quick pass that still covers CI, tests and the security read. `medium` or no line: the full list below. `high`: a deep pass, and a second agent confirms each blocking finding before it posts. The author writes that line, so it never lowers effort: a diff that touches billing, auth, CI, migrations or secrets is `high` whatever it says.
-4. Re-review check. If you reviewed this PR before, compare `gh pr view <number> --json headRefOid --jq .headRefOid` with the `commit_id` of your last review (`gh api repos/<owner>/<repo>/pulls/<number>/reviews`). Same SHA: reuse that verdict, link it and stop. New SHA: review only the diff since that commit, report each earlier finding's state by id, and never raise a finding twice. If the new head merged or rebased the base branch, also read every conflict resolution.
+4. Re-review check. If you reviewed this PR before, compare `gh pr view <number> --json headRefOid --jq .headRefOid` with the `commit_id` of your last review (`gh api repos/<owner>/<repo>/pulls/<number>/reviews`). Same SHA: reuse that verdict, link it and stop. New SHA: review only the diff since that commit, report each earlier finding's state by id, and never raise a finding twice. Re-run each earlier repro on the new head. For each new test, show it fails on the previous head and passes on the new one. Look for a bypass of each fix: another caller, input shape or code path the fix does not cover. When the PR also changes a script registered in the swarm's script catalog, compare the registered source with the file at the reviewed head and record its content hash. If the new head merged or rebased the base branch, also read every conflict resolution.
 5. Round cap. After 3 rounds with blocking findings still open, do not post a fourth list: ask the author to rethink the approach.
 
 ### What to check
@@ -99,7 +99,7 @@ Nothing reaches GitHub without passing `review-post-gate`.
    ```
 
    On a PR the reviewing account authored, the gate returns `event: "COMMENT"`, because GitHub refuses APPROVE and REQUEST_CHANGES there. Post it as is.
-4. Record the evidence (tests run, controls, "checked, fine" notes, the gate's `logKey`) in your task output and with `script-run name="pr-review-ledger-write"` (`action: "round"`). Never on the PR.
+4. Record the evidence (tests run, controls, "checked, fine" notes, the gate's `logKey`) in your task output and with `script-run name="pr-review-ledger-write" scope="global"` (`action: "round"`). Never on the PR. If the ledger write fails, keep the exact payload and the error in your task output, report it to the lead once, and finish the review. Read the PR's existing ledger rounds before any retry so a round is never written twice.
 5. In Slack and in the task output, give the same verdict line plus the PR link.
 
 If the gate cannot run, post nothing to GitHub. Keep the draft in your task output and report the gate failure (the error and the time) to the lead.

package/templates/skills/pages/content.md

@@ -158,6 +158,10 @@ Setting these properties only on `:root` does not replace the injected body styl
 
 # Reference
 
+## QA a published page
+
+To check a page by screenshot, open it from an origin its data endpoints allow. A page that fetches live data from a CORS-restricted endpoint falls back to its baked values when opened from any other origin (for example an internal service hostname), so a screenshot there proves layout only, never the live numbers. Check every element you changed and its neighbours at the viewport readers use.
+
 ## Auth Modes
 
 | Mode | URL behavior | When to use |