@desplega.ai/agent-swarm 2.4.0 → 2.4.1

package/src/types.ts

@@ -1362,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(),
@@ -1421,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),
   })
@@ -2210,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-website.ts

@@ -71,34 +71,71 @@ export function isFilledOrgLogoUrl(
   }
 }
 
+/**
+ * Free-mail providers with regional domains, matched on the label before the
+ * public suffix: hotmail.es, yahoo.co.uk, gmx.net and yandex.com.tr all count.
+ */
+const FREE_MAIL_FAMILIES = new Set([
+  "aol",
+  "fastmail",
+  "gmail",
+  "gmx",
+  "googlemail",
+  "hotmail",
+  "icloud",
+  "live",
+  "msn",
+  "outlook",
+  "protonmail",
+  "rocketmail",
+  "yahoo",
+  "yandex",
+  "ymail",
+  "zoho",
+]);
+
+/** Free-mail providers on one domain only, where the label alone is too generic. */
 const FREE_MAIL_DOMAINS = new Set([
-  "gmail.com",
-  "googlemail.com",
-  "outlook.com",
-  "hotmail.com",
-  "live.com",
-  "msn.com",
-  "yahoo.com",
-  "icloud.com",
-  "me.com",
+  "126.com",
+  "163.com",
+  "comcast.net",
+  "daum.net",
+  "free.fr",
+  "hanmail.net",
+  "hey.com",
+  "libero.it",
   "mac.com",
-  "aol.com",
-  "proton.me",
-  "protonmail.com",
-  "gmx.com",
-  "gmx.de",
-  "yandex.com",
-  "yandex.ru",
   "mail.com",
-  "zoho.com",
+  "mail.ru",
+  "me.com",
+  "naver.com",
+  "orange.fr",
+  "pm.me",
+  "proton.me",
   "qq.com",
-  "163.com",
-  "hey.com",
-  "fastmail.com",
+  "rediffmail.com",
+  "sina.com",
+  "t-online.de",
+  "tutanota.com",
+  "web.de",
 ]);
 
+/** Second-level labels of a country code suffix (acme.co.uk, acme.com.br). */
+const SECOND_LEVEL_LABELS = new Set(["ac", "co", "com", "edu", "gov", "ne", "net", "or", "org"]);
+
+/** Whether `host` (a normalized hostname) belongs to a public free-mail provider. */
+function isFreeMailHost(host: string): boolean {
+  const labels = host.split(".");
+  const suffixLength = labels.length > 2 && SECOND_LEVEL_LABELS.has(labels.at(-2) ?? "") ? 2 : 1;
+  // mail.yahoo.co.uk becomes yahoo.co.uk.
+  const registrable = labels.slice(-(suffixLength + 1));
+  return (
+    FREE_MAIL_FAMILIES.has(registrable[0] ?? "") || FREE_MAIL_DOMAINS.has(registrable.join("."))
+  );
+}
+
 /** The admin's email domain as a website suggestion, or null for free-mail domains. */
 export function websiteSuggestion(orgDomain: string | null | undefined): string | null {
   const host = normalizeOrgWebsite(orgDomain);
-  return host && !FREE_MAIL_DOMAINS.has(host) ? host : null;
+  return host && !isFreeMailHost(host) ? host : null;
 }

package/src/workflows/recovery.ts

@@ -25,7 +25,12 @@ import {
 } from "./engine";
 import type { ExecutorRegistry } from "./executors/registry";
 import { getSecretInputKeys } from "./input";
-import { finalizeOrWait, resumeFromChildRun, resumeWaitState } from "./resume";
+import {
+  finalizeOrWait,
+  recoverResolvedWaitState,
+  resumeFromChildRun,
+  resumeWaitState,
+} from "./resume";
 import {
   checkpointPortStepAndResolveSuccessors,
   completeTaskStepAndResolveSuccessors,
@@ -392,21 +397,12 @@ async function recoverWaitStates(registry: ExecutorRegistry): Promise<number> {
 
   for (const stuck of stuckRuns) {
     try {
-      // Decide what status to (re)apply.
-      let resumeStatus: "fired" | "timeout";
-      let payload: unknown;
-
-      if (stuck.waitStatus === "fired") {
-        resumeStatus = "fired";
-        payload = stuck.firedPayload != null ? safeJsonParse(stuck.firedPayload) : undefined;
-      } else if (stuck.waitStatus === "timeout") {
-        resumeStatus = "timeout";
+      if (stuck.waitStatus === "pending") {
+        const status = stuck.waitMode === "time" ? "fired" : "timeout";
+        await resumeWaitState(stuck.waitId, status, undefined, registry);
       } else {
-        // pending + overdue
-        resumeStatus = stuck.waitMode === "time" ? "fired" : "timeout";
+        await recoverResolvedWaitState(stuck.waitId, registry);
       }
-
-      await resumeWaitState(stuck.waitId, resumeStatus, payload, registry);
       recovered++;
     } catch (err) {
       if (await failRunOnUnreadableReplay(stuck.runId, err)) continue;
@@ -417,14 +413,6 @@ async function recoverWaitStates(registry: ExecutorRegistry): Promise<number> {
   return recovered;
 }
 
-function safeJsonParse(s: string): unknown {
-  try {
-    return JSON.parse(s);
-  } catch {
-    return s;
-  }
-}
-
 /**
  * Get run IDs by status. Simple query since there's no dedicated function for this.
  */

package/src/workflows/resume.ts

@@ -711,6 +711,22 @@ export async function resumeWaitState(
   );
 }
 
+/** Finish a wait resolution that committed before its step was checkpointed. */
+export async function recoverResolvedWaitState(
+  waitId: string,
+  registry: ExecutorRegistry,
+): Promise<void> {
+  const waitRow = await getWaitStateById(waitId);
+  if (!waitRow) return;
+  const status = waitRow.status;
+  if (status !== "fired" && status !== "timeout") return;
+
+  // Replay the durable result; the step checkpoint arbitrates concurrent resumes.
+  await failClosedOnUnreadableReplay(waitRow.workflowRunId, waitRow.workflowRunStepId, () =>
+    resumeClaimedWait(waitRow, status, waitRow.firedPayload, registry),
+  );
+}
+
 async function resumeClaimedWait(
   waitRow: WaitStateRow,
   status: "fired" | "timeout",

package/src/workflows/task-step-routing.ts

@@ -2,12 +2,15 @@ import {
   detachTaskFromWorkflowRunStep,
   getDbClient,
   getTaskById,
+  getWorkflowRun,
   getWorkflowRunStep,
   updateWorkflowRun,
   updateWorkflowRunStep,
 } from "../be/db";
 import {
+  type RetryPolicy,
   RetryPolicySchema,
+  SUPERSEDED_WORKFLOW_TASK_REASON,
   type WorkflowDefinition,
   type WorkflowNode,
   type WorkflowRunStep,
@@ -17,7 +20,7 @@ import { getSuccessors } from "./definition";
 import { joinForeach, resolveForeachParent } from "./foreach-join";
 
 export interface PortStepRoutingResult {
-  /** False when another handler already moved the step out of `waiting`. */
+  /** False when the step was already claimed or its run is terminal. */
   claimed: boolean;
   successors: WorkflowNode[];
 }
@@ -85,6 +88,10 @@ export async function checkpointPortStepAndResolveSuccessors(
   return await getDbClient().transaction(async (): Promise<PortStepRoutingResult> => {
     const current = await getWorkflowRunStep(stepId);
     if (!current || current.status !== "waiting") return { claimed: false, successors: [] };
+    const run = await getWorkflowRun(runId);
+    if (!run || (run.status !== "waiting" && run.status !== "running")) {
+      return { claimed: false, successors: [] };
+    }
     await checkpointStep(runId, stepId, nodeId, { output, nextPort }, ctx);
     await updateWorkflowRun(runId, { status: "running" });
     return { claimed: true, successors: getSuccessors(def, nodeId, nextPort) };
@@ -97,15 +104,33 @@ export async function checkpointPortStepAndResolveSuccessors(
  * - `not-claimed`: another handler already moved the step out of `waiting`,
  *   or the failed task is no longer the one bound to the step (it was
  *   already retried and a fresh task now owns it); the caller stops.
- * - `not-eligible`: no retry applies (no `node.retry`, not an agent-task node,
- *   or retries exhausted); the caller applies `onNodeFailure` as before.
+ * - `not-eligible`: no retry applies (no `node.retry` and not a supersede
+ *   cut, not an agent-task node, or retries exhausted); the caller applies
+ *   `onNodeFailure` as before.
  */
 export type TaskStepRetryOutcome = "scheduled" | "not-claimed" | "not-eligible";
 
+/**
+ * Retry applied to an agent-task step whose task was cut by a supersede
+ * (deploy drain, heartbeat remediation) when the node declares no `retry`.
+ * The cut is not the task's fault, so the step gets one fresh attempt after
+ * the restart settles. An explicit `node.retry` always wins; `retry:
+ * { maxRetries: 0 }` opts a node with external side effects out.
+ */
+export const SUPERSEDE_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 1,
+  strategy: "static",
+  baseDelayMs: 30_000,
+  maxDelayMs: 30_000,
+};
+
 /**
  * Apply a node's `retry` policy to a FAILED agent-task step task. The sync
  * executor path does this in `executeStep`; an async agent-task step only
  * learns about the failure here, from `task.failed` or the recovery sweep.
+ * A node without `retry` gets `SUPERSEDE_RETRY_POLICY` when the task was
+ * failed with `SUPERSEDED_WORKFLOW_TASK_REASON`. The task row is checked as
+ * well as `reason`, because the recovery sweep passes its own reason text.
  *
  * In one transaction: re-claim the step while it is still `waiting` AND still
  * bound to the failed task, detach that task (the executor reuses any task
@@ -114,6 +139,9 @@ export type TaskStepRetryOutcome = "scheduled" | "not-claimed" | "not-eligible";
  * task. Bounded by `maxRetries` via the step's persisted `retryCount`, read
  * only after ownership is confirmed: a stale caller's step snapshot may carry
  * the counter of a newer attempt.
+ *
+ * Foreach children (`<foreachId>#<key>`) are not matched here: the retry
+ * poller resolves nodes by exact id and cannot re-dispatch a child yet.
  */
 export async function scheduleTaskStepRetry(
   def: WorkflowDefinition,
@@ -123,10 +151,16 @@ export async function scheduleTaskStepRetry(
   reason: string,
 ): Promise<TaskStepRetryOutcome> {
   const node = def.nodes.find((n) => n.id === step.nodeId);
-  if (!node || node.type !== "agent-task" || !node.retry) return "not-eligible";
-  const parsed = RetryPolicySchema.safeParse(node.retry);
-  if (!parsed.success) return "not-eligible";
-  const policy = parsed.data;
+  if (!node || node.type !== "agent-task") return "not-eligible";
+  let policy: RetryPolicy;
+  if (node.retry) {
+    const parsed = RetryPolicySchema.safeParse(node.retry);
+    if (!parsed.success) return "not-eligible";
+    policy = parsed.data;
+  } else {
+    if (!(await isSupersedeCut(taskId, reason))) return "not-eligible";
+    policy = SUPERSEDE_RETRY_POLICY;
+  }
 
   return await getDbClient().transaction(async (): Promise<TaskStepRetryOutcome> => {
     const current = await getWorkflowRunStep(step.id);
@@ -139,6 +173,12 @@ export async function scheduleTaskStepRetry(
   });
 }
 
+async function isSupersedeCut(taskId: string, reason: string): Promise<boolean> {
+  if (reason === SUPERSEDED_WORKFLOW_TASK_REASON) return true;
+  const task = await getTaskById(taskId);
+  return task?.failureReason === SUPERSEDED_WORKFLOW_TASK_REASON;
+}
+
 export interface TaskStepRoutingResult {
   /**
    * False when another handler already moved the step out of `waiting` — the

package/templates/skills/apps/SKILL.md

@@ -18,6 +18,14 @@ Swarm Apps are persistent, agent-authored internal applications: a schema-backed
 | `app-upsert` | Create an app, or replace an existing app's entire definition when you intentionally have the full desired state. |
 | `app-patch` | Make a focused change while preserving everything not mentioned in the patch. Prefer this for iteration. |
 | `app-query` | Run one declared named query and return its rows. Use this when an agent or saved script needs to consume app data rather than render the app UI. |
+| `app-rows-list` | List rows with typed equality filters, sorting, and a limit. Returns `{ rows, total }`. |
+| `app-row-get` | Read a row by `rowId`. Returns `{ row }`. |
+| `app-row-create` | Create a row from `values`. Returns `{ row }`. |
+| `app-rows-create` | Create 1 to 500 rows from a `rows: values[]` array, within 10 MiB. Returns `{ rows }`. |
+| `app-row-patch` | Patch a row by `rowId` with `values`. Returns `{ row }`. |
+| `app-row-delete` | Delete a row by `rowId`. Returns `{ ok: true }`. |
+| `app-rows-delete` | Delete matching rows with a non-empty `equals` filter. Returns `{ deleted }`. |
+| `app-action-run` | Run a declared script, task, or sync action with `{ appId, action, input? }`. Agents can invoke it through MCP only. |
 | `app-history` | List definition snapshots and their compact model/column digests before choosing a restore point. |
 | `app-diff` | Show a unified definition diff; defaults to newest snapshot → CURRENT. |
 | `app-rollback` | Restore a snapshot through the normal schema-migration engine. |
@@ -28,7 +36,24 @@ For every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch`
 
 ### Reading an app's callable surface
 
-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.
+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 `app-action-run` or `POST /api/apps/<id>/actions/<name>` (a `script` action runs its script, a `task` action spawns a task, a `sync` action refreshes sources). Read the query parameters and action arguments from the definition before invocation. 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.
 
 ### Verified action caller
 
@@ -372,7 +397,7 @@ Use a task action named Tackle when a person should hand one issue row to the sw
 
 For direct MCP calls, `app-query` accepts `{ appId, query, params? }` and returns rows from that declared named query; every supplied param must be referenced by a `$param` filter in that query. Use it when an agent needs to read app state without scraping the UI.
 
-Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. Actions stay REST-only from scripts — there is no SDK method to invoke them.
+Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. Scripts can create, list, get, patch, and delete rows with the seven row tools. Actions remain REST/MCP-only and have no script SDK method.
 
 ### Pages, routes, and page trees
 
@@ -764,3 +789,17 @@ The tool returns `{ appId, url: "/apps/<id>" }`. Open that URL to verify the liv
 - Logged-in browser: a fresh dashboard has no connection and redirects to /setup. Seed the localStorage key `agent-swarm-connections` with `{connections:[{id,name,apiUrl,apiKey}],activeId}`. Build the value from an env var and pipe it to `agent-browser eval --stdin`, so the key never reaches a command line. Reload, then pick a user in the "Who are you?" dialog.
 - Apps scroll inside an inner canvas, so a full-page screenshot captures only the viewport. Scroll the canvas or raise the viewport height. For mobile, set a 375px-wide viewport before the screenshot.
 - App definitions: `GET /api/apps` and `GET /api/apps/<id>` with the API key as Bearer.
+
+
+### Rows from agents and scripts
+
+Every row tool requires `appId` and `model`. Scripts use underscore names, such as `ctx.swarm.app_row_create` and `ctx.swarm.app_rows_list`.
+Results use the usual `data` wrapper, so scripts read `res?.data ?? res`. Rows contain system fields and declared columns at the top level.
+Writes record `agent:<agentId>` in `createdBy` and `updatedBy`. Source projections and join keys remain read-only. Each row input must fit within 1 MiB.
+
+`app-rows-list` accepts `equals`, `sort: "<column>:asc|desc"`, and `limit` from 1 to 1000 (default 200).
+Equality filters accept declared columns and system columns. Filter values must match the column kind and use strict equality.
+`app-rows-delete` requires at least one equality filter and accepts a limit from 1 to 1000 (default 1000).
+
+`app-action-run` returns the REST action body under `data`. Script actions run with the script owner's identity and receive the verified invoking agent as `caller`.
+Scripts and extensions cannot invoke `app-action-run`.

package/templates/skills/apps/content.md

@@ -13,6 +13,14 @@ Swarm Apps are persistent, agent-authored internal applications: a schema-backed
 | `app-upsert` | Create an app, or replace an existing app's entire definition when you intentionally have the full desired state. |
 | `app-patch` | Make a focused change while preserving everything not mentioned in the patch. Prefer this for iteration. |
 | `app-query` | Run one declared named query and return its rows. Use this when an agent or saved script needs to consume app data rather than render the app UI. |
+| `app-rows-list` | List rows with typed equality filters, sorting, and a limit. Returns `{ rows, total }`. |
+| `app-row-get` | Read a row by `rowId`. Returns `{ row }`. |
+| `app-row-create` | Create a row from `values`. Returns `{ row }`. |
+| `app-rows-create` | Create 1 to 500 rows from a `rows: values[]` array, within 10 MiB. Returns `{ rows }`. |
+| `app-row-patch` | Patch a row by `rowId` with `values`. Returns `{ row }`. |
+| `app-row-delete` | Delete a row by `rowId`. Returns `{ ok: true }`. |
+| `app-rows-delete` | Delete matching rows with a non-empty `equals` filter. Returns `{ deleted }`. |
+| `app-action-run` | Run a declared script, task, or sync action with `{ appId, action, input? }`. Agents can invoke it through MCP only. |
 | `app-history` | List definition snapshots and their compact model/column digests before choosing a restore point. |
 | `app-diff` | Show a unified definition diff; defaults to newest snapshot → CURRENT. |
 | `app-rollback` | Restore a snapshot through the normal schema-migration engine. |
@@ -23,7 +31,24 @@ For every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch`
 
 ### Reading an app's callable surface
 
-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.
+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 `app-action-run` or `POST /api/apps/<id>/actions/<name>` (a `script` action runs its script, a `task` action spawns a task, a `sync` action refreshes sources). Read the query parameters and action arguments from the definition before invocation. 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.
 
 ### Verified action caller
 
@@ -367,7 +392,7 @@ Use a task action named Tackle when a person should hand one issue row to the sw
 
 For direct MCP calls, `app-query` accepts `{ appId, query, params? }` and returns rows from that declared named query; every supplied param must be referenced by a `$param` filter in that query. Use it when an agent needs to read app state without scraping the UI.
 
-Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. Actions stay REST-only from scripts — there is no SDK method to invoke them.
+Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. Scripts can create, list, get, patch, and delete rows with the seven row tools. Actions remain REST/MCP-only and have no script SDK method.
 
 ### Pages, routes, and page trees
 
@@ -759,3 +784,17 @@ The tool returns `{ appId, url: "/apps/<id>" }`. Open that URL to verify the liv
 - Logged-in browser: a fresh dashboard has no connection and redirects to /setup. Seed the localStorage key `agent-swarm-connections` with `{connections:[{id,name,apiUrl,apiKey}],activeId}`. Build the value from an env var and pipe it to `agent-browser eval --stdin`, so the key never reaches a command line. Reload, then pick a user in the "Who are you?" dialog.
 - Apps scroll inside an inner canvas, so a full-page screenshot captures only the viewport. Scroll the canvas or raise the viewport height. For mobile, set a 375px-wide viewport before the screenshot.
 - App definitions: `GET /api/apps` and `GET /api/apps/<id>` with the API key as Bearer.
+
+
+### Rows from agents and scripts
+
+Every row tool requires `appId` and `model`. Scripts use underscore names, such as `ctx.swarm.app_row_create` and `ctx.swarm.app_rows_list`.
+Results use the usual `data` wrapper, so scripts read `res?.data ?? res`. Rows contain system fields and declared columns at the top level.
+Writes record `agent:<agentId>` in `createdBy` and `updatedBy`. Source projections and join keys remain read-only. Each row input must fit within 1 MiB.
+
+`app-rows-list` accepts `equals`, `sort: "<column>:asc|desc"`, and `limit` from 1 to 1000 (default 200).
+Equality filters accept declared columns and system columns. Filter values must match the column kind and use strict equality.
+`app-rows-delete` requires at least one equality filter and accepts a limit from 1 to 1000 (default 1000).
+
+`app-action-run` returns the REST action body under `data`. Script actions run with the script owner's identity and receive the verified invoking agent as `caller`.
+Scripts and extensions cannot invoke `app-action-run`.

package/dist/handlers-zbs90bny.js

@@ -1,39 +0,0 @@
-import {
-  isUserAllowed2,
-  registerMessageHandler2
-} from "./cli-avmqhatn.js";
-import"./cli-1cevz46c.js";
-import"./cli-x1p5dhq2.js";
-import"./cli-x719j3vs.js";
-import"./cli-rdr166ht.js";
-import"./cli-2rwet3r7.js";
-import"./cli-qz93y3x5.js";
-import"./cli-3h26v7yj.js";
-import"./cli-7a91w22y.js";
-import"./cli-ttaz6c7m.js";
-import"./cli-nrrg0fvy.js";
-import"./cli-3ggwdtb0.js";
-import"./cli-b80a1100.js";
-import"./cli-kk2r80n5.js";
-import"./cli-tg9ksbn8.js";
-import"./cli-qje9k2nh.js";
-import"./cli-nme7wery.js";
-import"./cli-tj4j2ts4.js";
-import"./cli-bn26xbcs.js";
-import"./cli-vjfpshn3.js";
-import"./cli-02vhhssk.js";
-import"./cli-13p25grh.js";
-import"./cli-0adyhvq2.js";
-import"./cli-4fhyq711.js";
-import"./cli-xfe63zx3.js";
-import"./cli-6ftrrwm1.js";
-import"./cli-8cxkw1f5.js";
-import"./cli-445c1vp7.js";
-import"./cli-kvzgak7c.js";
-import"./cli-5s5hx57y.js";
-import"./cli-rg7ntypm.js";
-import"./cli-ptkpaqfy.js";
-export {
-  isUserAllowed2 as isUserAllowed,
-  registerMessageHandler2 as registerMessageHandler
-};

package/dist/index-8pwc1jc8.js

@@ -1,40 +0,0 @@
-import {
-  calculateNextRun2,
-  startScheduler2,
-  stopScheduler2,
-  runScheduleNow2
-} from "./cli-x719j3vs.js";
-import"./cli-rdr166ht.js";
-import"./cli-2rwet3r7.js";
-import"./cli-qz93y3x5.js";
-import"./cli-3h26v7yj.js";
-import"./cli-7a91w22y.js";
-import"./cli-ttaz6c7m.js";
-import"./cli-nrrg0fvy.js";
-import"./cli-3ggwdtb0.js";
-import"./cli-b80a1100.js";
-import"./cli-kk2r80n5.js";
-import"./cli-tg9ksbn8.js";
-import"./cli-qje9k2nh.js";
-import"./cli-nme7wery.js";
-import"./cli-tj4j2ts4.js";
-import"./cli-bn26xbcs.js";
-import"./cli-vjfpshn3.js";
-import"./cli-02vhhssk.js";
-import"./cli-13p25grh.js";
-import"./cli-0adyhvq2.js";
-import"./cli-4fhyq711.js";
-import"./cli-xfe63zx3.js";
-import"./cli-6ftrrwm1.js";
-import"./cli-8cxkw1f5.js";
-import"./cli-445c1vp7.js";
-import"./cli-kvzgak7c.js";
-import"./cli-5s5hx57y.js";
-import"./cli-rg7ntypm.js";
-import"./cli-ptkpaqfy.js";
-export {
-  calculateNextRun2 as calculateNextRun,
-  runScheduleNow2 as runScheduleNow,
-  startScheduler2 as startScheduler,
-  stopScheduler2 as stopScheduler
-};

package/dist/index-nxa6me0q.js

@@ -1,41 +0,0 @@
-import"./cli-ns59dc6r.js";
-import {
-  startHeartbeat2,
-  stopHeartbeat2
-} from "./cli-bhwa8rzc.js";
-import"./cli-rsd7ga7v.js";
-import"./cli-eqgfs202.js";
-import"./cli-x719j3vs.js";
-import"./cli-rdr166ht.js";
-import"./cli-2rwet3r7.js";
-import"./cli-qz93y3x5.js";
-import"./cli-3h26v7yj.js";
-import"./cli-7a91w22y.js";
-import"./cli-ttaz6c7m.js";
-import"./cli-nrrg0fvy.js";
-import"./cli-3ggwdtb0.js";
-import"./cli-b80a1100.js";
-import"./cli-kk2r80n5.js";
-import"./cli-tg9ksbn8.js";
-import"./cli-qje9k2nh.js";
-import"./cli-nme7wery.js";
-import"./cli-tj4j2ts4.js";
-import"./cli-bn26xbcs.js";
-import"./cli-vjfpshn3.js";
-import"./cli-02vhhssk.js";
-import"./cli-13p25grh.js";
-import"./cli-0adyhvq2.js";
-import"./cli-4fhyq711.js";
-import"./cli-xfe63zx3.js";
-import"./cli-6ftrrwm1.js";
-import"./cli-8cxkw1f5.js";
-import"./cli-445c1vp7.js";
-import"./cli-kvzgak7c.js";
-import"./cli-b2mz5mjc.js";
-import"./cli-5s5hx57y.js";
-import"./cli-rg7ntypm.js";
-import"./cli-ptkpaqfy.js";
-export {
-  startHeartbeat2 as startHeartbeat,
-  stopHeartbeat2 as stopHeartbeat
-};