@desplega.ai/agent-swarm 2.3.0 → 2.4.1

package/src/tools/app-rows.ts

@@ -0,0 +1,234 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { AppNameSchema, type ModelDef, SYSTEM_COLUMN_KINDS } from "../apps/definition";
+import {
+  type AppRow,
+  AppRowAppNotFoundError,
+  AppRowValidationError,
+  createAppRow,
+  createAppRows,
+  deleteAppRow,
+  getAppRow,
+  patchAppRow,
+  validValue,
+} from "../apps/row-store";
+import { appDefinitionNeedsRepair, getApp } from "../apps/store";
+import { getAgentById } from "../be/db";
+import {
+  MAX_APP_BULK_ROWS_BODY_BYTES,
+  MAX_APP_ROW_BODY_BYTES,
+  rowMatchesFilters,
+  selectAppRows,
+} from "../http/apps";
+import { can } from "../rbac";
+import {
+  createToolRegistrar,
+  type SwarmToolResult,
+  swarmToolOutputSchema,
+  toolErr,
+  toolOk,
+} from "./utils";
+
+const base = { appId: z.string().min(1), model: AppNameSchema };
+const rowId = z.string().min(1);
+const values = z.record(z.string(), z.unknown());
+const equals = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
+const limit = z.number().int().min(1).max(1000);
+const rowOutput = { row: z.looseObject({}).optional() };
+const rowsOutput = { rows: z.array(z.looseObject({})).optional() };
+
+function checkSize(value: unknown, max: number): void {
+  if (Buffer.byteLength(JSON.stringify(value), "utf8") > max) {
+    throw new AppRowValidationError([
+      { path: "values", message: `Row input exceeds ${max} bytes.` },
+    ]);
+  }
+}
+
+function rowFilters(model: ModelDef, equals: Record<string, string | number | boolean> = {}) {
+  return Object.entries(equals).map(([column, value]) => {
+    const declared = Object.hasOwn(model.columns, column) ? model.columns[column] : undefined;
+    if ((!declared && !Object.hasOwn(SYSTEM_COLUMN_KINDS, column)) || declared?.hidden) {
+      throw new AppRowValidationError([
+        { path: `equals.${column}`, message: "Unknown or hidden column." },
+      ]);
+    }
+    if (!validValue(declared ?? { kind: SYSTEM_COLUMN_KINDS[column]! }, value)) {
+      throw new AppRowValidationError([
+        { path: `equals.${column}`, message: "Filter value must match the column kind." },
+      ]);
+    }
+    return { column, value };
+  });
+}
+
+export function registerAppRowTools(server: McpServer) {
+  function register<Shape extends z.ZodRawShape>(
+    name: string,
+    description: string,
+    shape: Shape,
+    output: z.ZodRawShape,
+    operation: (
+      args: z.infer<z.ZodObject<typeof base & Shape>>,
+      model: ModelDef,
+      actor: string,
+    ) => Promise<SwarmToolResult>,
+    readOnly = false,
+  ) {
+    createToolRegistrar(server)(
+      name,
+      {
+        title: description,
+        description,
+        annotations: { readOnlyHint: readOnly },
+        rbac: { permission: "app.use" },
+        inputSchema: z.object({ ...base, ...shape }),
+        outputSchema: swarmToolOutputSchema(output),
+      },
+      async (args, info) => {
+        if (!info.agentId) return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
+        const { appId, model: modelName } = z.object(base).parse(args);
+        const agent = await getAgentById(info.agentId);
+        const decision = can({
+          principal: { kind: "agent", agentId: info.agentId, isLead: agent?.isLead ?? false },
+          verb: "app.use",
+          resource: { kind: "app", appId },
+          source: "mcp",
+        });
+        if (!decision.allow) return toolErr(decision.reason);
+        const app = await getApp(appId);
+        if (!app) return toolErr("App not found.");
+        if (appDefinitionNeedsRepair(app))
+          return toolErr("App definition needs repair.", { data: { issues: app.definitionError } });
+        if (!Object.hasOwn(app.definition.models, modelName)) return toolErr("Model not found.");
+        try {
+          return await operation(args, app.definition.models[modelName]!, `agent:${info.agentId}`);
+        } catch (error) {
+          if (error instanceof AppRowValidationError)
+            return toolErr(error.message, { data: { issues: error.issues } });
+          if (error instanceof AppRowAppNotFoundError) return toolErr(error.message);
+          throw error;
+        }
+      },
+    );
+  }
+
+  register(
+    "app-rows-list",
+    "List app rows with equality filters, sorting, and a limit.",
+    {
+      equals: equals.optional(),
+      sort: z.string().optional(),
+      limit: limit.optional(),
+    },
+    { ...rowsOutput, total: z.number().optional() },
+    async (args, model) => {
+      const data = await selectAppRows(
+        args.appId,
+        args.model,
+        model,
+        rowFilters(model, args.equals),
+        args.sort,
+        args.limit,
+        true,
+      );
+      return toolOk(`Found ${data.total} row(s).`, { data });
+    },
+    true,
+  );
+
+  register(
+    "app-row-get",
+    "Get an app row.",
+    { rowId },
+    rowOutput,
+    async (args) => {
+      const row = await getAppRow(args.appId, args.model, args.rowId);
+      return row ? toolOk("Row retrieved.", { data: { row } }) : toolErr("Row not found.");
+    },
+    true,
+  );
+
+  register(
+    "app-row-create",
+    "Create an app row.",
+    { values },
+    rowOutput,
+    async (args, model, actor) => {
+      checkSize({ values: args.values }, MAX_APP_ROW_BODY_BYTES);
+      const row = await createAppRow(args.appId, args.model, model, args.values, { actor });
+      return toolOk("Row created.", { data: { row } });
+    },
+  );
+
+  register(
+    "app-rows-create",
+    "Create up to 500 app rows within 10 MiB.",
+    {
+      rows: z.array(values).min(1).max(500),
+    },
+    rowsOutput,
+    async (args, model, actor) => {
+      checkSize({ rows: args.rows }, MAX_APP_BULK_ROWS_BODY_BYTES);
+      for (const values of args.rows) checkSize({ values }, MAX_APP_ROW_BODY_BYTES);
+      const rows = await createAppRows(args.appId, args.model, model, args.rows, { actor });
+      return toolOk(`Created ${rows.length} row(s).`, { data: { rows } });
+    },
+  );
+
+  register(
+    "app-row-patch",
+    "Patch an app row.",
+    { rowId, values },
+    rowOutput,
+    async (args, model, actor) => {
+      checkSize({ values: args.values }, MAX_APP_ROW_BODY_BYTES);
+      const row = await patchAppRow(args.appId, args.model, model, args.rowId, args.values, {
+        actor,
+      });
+      return row ? toolOk("Row updated.", { data: { row } }) : toolErr("Row not found.");
+    },
+  );
+
+  register(
+    "app-row-delete",
+    "Delete an app row.",
+    { rowId },
+    { ok: z.boolean().optional() },
+    async (args, model) => {
+      const deleted = await deleteAppRow(args.appId, args.model, model, args.rowId);
+      return deleted ? toolOk("Row deleted.", { data: { ok: true } }) : toolErr("Row not found.");
+    },
+  );
+
+  register(
+    "app-rows-delete",
+    "Delete matching app rows. Supply at least one equality filter.",
+    {
+      equals: equals.refine(
+        (value) => Object.keys(value).length > 0,
+        "Supply at least one equality filter.",
+      ),
+      limit: limit.optional(),
+    },
+    { deleted: z.number().optional() },
+    async (args, model) => {
+      const filters = rowFilters(model, args.equals);
+      const { rows } = await selectAppRows(
+        args.appId,
+        args.model,
+        model,
+        filters,
+        undefined,
+        args.limit ?? 1000,
+        true,
+      );
+      // Re-check under the row lock: a row patched out of the filter since the select is kept.
+      const matches = (row: AppRow) => rowMatchesFilters(row, filters);
+      let deleted = 0;
+      for (const row of rows)
+        if (await deleteAppRow(args.appId, args.model, model, row.id, matches)) deleted++;
+      return toolOk(`Deleted ${deleted} row(s).`, { data: { deleted } });
+    },
+  );
+}

package/src/tools/model-catalog/index.ts

@@ -87,7 +87,7 @@ export const registerModelCatalogOverlayUpsertTool = (server: McpServer) => {
           .string()
           .min(1)
           .describe(
-            `models.dev provider id: anthropic, openai, openrouter, amazon-bedrock, opencode, ${openAICompatibleProviderIds().join(", ")}.`,
+            `models.dev provider id: anthropic, openai, openrouter, amazon-bedrock, opencode, opencode-go, ${openAICompatibleProviderIds().join(", ")}.`,
           ),
         modelId: z
           .string()

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/tools/tool-config.ts

@@ -189,6 +189,14 @@ export const DEFERRED_TOOLS = new Set([
   "app-list",
   "app-patch",
   "app-query",
+  "app-rows-list",
+  "app-row-get",
+  "app-row-create",
+  "app-rows-create",
+  "app-row-patch",
+  "app-row-delete",
+  "app-rows-delete",
+  "app-action-run",
   "app-sync",
   "app-upsert",
   "app-history",

package/src/tools/utils.ts

@@ -347,7 +347,7 @@ export const NUDGES: Record<string, (result: SwarmToolResult) => string | undefi
     const hasQueries = Object.keys(definition?.queries ?? {}).length > 0;
     const hasActions = Object.keys(definition?.actions ?? {}).length > 0;
     return hasQueries || hasActions
-      ? "This app's callable surface is `definition.queries` (run with `app-query`, passing any `$param` values) and `definition.actions` (invoke with `POST /api/apps/<id>/actions/<name>`; `sync` actions refresh sources)."
+      ? "Run `definition.queries` with `app-query` and supply each `$param` value. Invoke `definition.actions` with `app-action-run` through MCP or `POST /api/apps/<id>/actions/<name>` through REST. Sync actions refresh sources."
       : undefined;
   },
   // kv-get is spill-exempt (retrieval path), so oversized values reach the

package/src/tools/workflows/retry-workflow-run.ts

@@ -10,7 +10,7 @@ export const registerRetryWorkflowRunTool = (server: McpServer) => {
       title: "Retry Workflow Run",
       annotations: { destructiveHint: false },
       description:
-        "Retry a failed workflow run from the beginning. The run must be in 'failed' status.",
+        "Resume the same failed workflow run from its failed step(s); completed steps are not re-run. Retrying re-creates the failed node's side effects (e.g. an agent task), so check the target state first if that work was already done manually.",
       inputSchema: z.object({
         runId: z.string().uuid().describe("Workflow run ID to retry"),
       }),

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
 // ============================================================================
@@ -1327,6 +1362,14 @@ export const AgentBedrockStatusSchema = z
   .openapi("AgentBedrockStatus");
 export type AgentBedrockStatus = z.infer<typeof AgentBedrockStatusSchema>;
 
+export const AgentOpencodeGoStatusSchema = z
+  .object({
+    probedAt: z.number(), // unix ms
+    models: z.array(z.string()).default([]),
+  })
+  .openapi("AgentOpencodeGoStatus");
+export type AgentOpencodeGoStatus = z.infer<typeof AgentOpencodeGoStatusSchema>;
+
 const AcpSessionConfigSelectValueSchema = z.object({
   value: z.string(),
   name: z.string(),
@@ -1386,6 +1429,8 @@ export const AgentCredStatusSchema = z
     reportKind: z.enum(["boot", "post_task"]).default("boot"),
     /** Pi-mono Bedrock enumeration block — null when not in Bedrock mode. */
     bedrock: AgentBedrockStatusSchema.nullable().default(null),
+    /** Pi-mono only: the `opencode-go` model ids the worker's pi-ai resolves. */
+    opencodeGo: AgentOpencodeGoStatusSchema.nullable().default(null),
     /** ACP options advertised by the most recently created session. */
     acp: AgentAcpStatusSchema.nullable().default(null),
   })
@@ -2175,6 +2220,13 @@ export const RetryPolicySchema = z
   .openapi("RetryPolicy");
 export type RetryPolicy = z.infer<typeof RetryPolicySchema>;
 
+/**
+ * `failureReason` of a workflow-step task cut by a supersede (deploy drain,
+ * heartbeat remediation). The workflow engine re-dispatches it once even
+ * when the node declares no `retry` (see `scheduleTaskStepRetry`).
+ */
+export const SUPERSEDED_WORKFLOW_TASK_REASON = "superseded_workflow_task";
+
 // --- Executor Metadata ---
 
 export const ExecutorMetaSchema = z

package/src/utils/company-profile.ts

@@ -0,0 +1,24 @@
+export const COMPANY_TEAM_SIZES = ["1", "2-10", "11-50", "51+"] as const;
+
+export const COMPANY_USE_CASES = ["features", "bugs", "review", "ops", "docs", "data"] as const;
+
+export const COMPANY_ACQUISITION_SOURCES = [
+  "search",
+  "github",
+  "social",
+  "colleague",
+  "newsletter",
+  "event",
+  "ai_assistant",
+  "hacker_news",
+  "other",
+] as const;
+
+export const USER_FUNCTIONS = [
+  "engineer",
+  "eng_lead",
+  "founder",
+  "product",
+  "ops",
+  "other",
+] as const;

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 };
+}