@desplega.ai/agent-swarm 2.3.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
 // ============================================================================

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/dist/handlers-tb3xgjnm.js

@@ -1,37 +0,0 @@
-import {
-  isUserAllowed2,
-  registerMessageHandler2
-} from "./cli-4hmaheb6.js";
-import"./cli-30m5q8mc.js";
-import"./cli-y3dvz6ge.js";
-import"./cli-8qsx817b.js";
-import"./cli-rdr166ht.js";
-import"./cli-fhvqt2fp.js";
-import"./cli-qz93y3x5.js";
-import"./cli-65q70v2v.js";
-import"./cli-3h26v7yj.js";
-import"./cli-7a91w22y.js";
-import"./cli-3ggwdtb0.js";
-import"./cli-g6p7c2my.js";
-import"./cli-xgn4rwyv.js";
-import"./cli-kqypty34.js";
-import"./cli-qrwp40st.js";
-import"./cli-qje9k2nh.js";
-import"./cli-jhmjwqcg.js";
-import"./cli-q1812jbw.js";
-import"./cli-8cvvytad.js";
-import"./cli-vjfpshn3.js";
-import"./cli-13p25grh.js";
-import"./cli-0adyhvq2.js";
-import"./cli-dxwh4j32.js";
-import"./cli-9e9kjqsj.js";
-import"./cli-hz64bcnj.js";
-import"./cli-445c1vp7.js";
-import"./cli-kvzgak7c.js";
-import"./cli-6vcyw6v7.js";
-import"./cli-re4wkbzx.js";
-import"./cli-ptkpaqfy.js";
-export {
-  isUserAllowed2 as isUserAllowed,
-  registerMessageHandler2 as registerMessageHandler
-};