@desplega.ai/agent-swarm 2.4.0 → 2.4.1

package/src/tests/workflow-agent-task-retry.test.ts

@@ -13,8 +13,14 @@ import {
   getWorkflowRun,
   getWorkflowRunStepsByRunId,
   initDb,
+  updateWorkflowRunStep,
 } from "../be/db";
-import type { AgentTask, WorkflowDefinition, WorkflowRunStep } from "../types";
+import {
+  type AgentTask,
+  SUPERSEDED_WORKFLOW_TASK_REASON,
+  type WorkflowDefinition,
+  type WorkflowRunStep,
+} from "../types";
 import { startWorkflowExecution } from "../workflows/engine";
 import { workflowEventBus } from "../workflows/event-bus";
 import { AgentTaskExecutor } from "../workflows/executors/agent-task";
@@ -27,6 +33,7 @@ import { ExecutorRegistry } from "../workflows/executors/registry";
 import { recoverIncompleteRuns } from "../workflows/recovery";
 import { setupWorkflowResumeListener } from "../workflows/resume";
 import { startRetryPoller, stopRetryPoller } from "../workflows/retry-poller";
+import { SUPERSEDE_RETRY_POLICY } from "../workflows/task-step-routing";
 import { interpolate } from "../workflows/template";
 
 const TEST_DB_PATH = "./test-workflow-agent-task-retry.sqlite";
@@ -217,18 +224,18 @@ describe("agent-task node.retry on task failure", () => {
     expect((await getTaskByWorkflowRunStepId(step.id))!.id).toBe(second.id);
   });
 
-  test("a node without retry fails the run exactly as before", async () => {
+  test("a node without retry fails the run exactly as before on a non-supersede failure", async () => {
     const runId = await startRun({});
     const step = await synthesizeStep(runId);
     const first = (await getTaskByWorkflowRunStepId(step.id))!;
 
-    await failTask(first.id, "superseded_workflow_task");
+    await failTask(first.id, "agent crashed");
 
     const run = await waitFor(async () => {
       const r = await getWorkflowRun(runId);
       return r?.status === "failed" ? r : null;
     }, "run failed");
-    expect(run.error).toContain("superseded_workflow_task");
+    expect(run.error).toContain("agent crashed");
     const failedStep = await synthesizeStep(runId);
     expect(failedStep.status).toBe("failed");
     expect(failedStep.retryCount).toBe(0);
@@ -281,6 +288,125 @@ describe("agent-task node.retry on task failure", () => {
   });
 });
 
+/** Wait for the step to be queued for the poller, then make it due now. */
+async function waitForQueuedRetry(runId: string): Promise<WorkflowRunStep> {
+  const queued = await waitFor(async () => {
+    const s = await synthesizeStep(runId);
+    return s.status === "failed" && s.nextRetryAt != null ? s : null;
+  }, "step queued for retry");
+  await updateWorkflowRunStep(queued.id, { nextRetryAt: new Date(Date.now() - 1).toISOString() });
+  return queued;
+}
+
+describe("implicit retry for a superseded task on a node without retry", () => {
+  test("a cut is redriven once after the static delay; a second cut follows onNodeFailure", async () => {
+    const runId = await startRun({});
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    const cutAt = Date.now();
+    await failTask(first.id, SUPERSEDED_WORKFLOW_TASK_REASON);
+
+    const queued = await waitFor(async () => {
+      const s = await synthesizeStep(runId);
+      return s.status === "failed" && s.nextRetryAt != null ? s : null;
+    }, "step queued for retry");
+    expect(queued.retryCount).toBe(1);
+    expect(queued.maxRetries).toBe(1);
+    expect(queued.error).toBe(SUPERSEDED_WORKFLOW_TASK_REASON);
+    const delayMs = new Date(queued.nextRetryAt!).getTime() - cutAt;
+    expect(delayMs).toBeGreaterThanOrEqual(SUPERSEDE_RETRY_POLICY.baseDelayMs - 1000);
+    expect(delayMs).toBeLessThanOrEqual(SUPERSEDE_RETRY_POLICY.baseDelayMs + 5000);
+    expect((await getWorkflowRun(runId))!.status).toBe("waiting");
+    expect((await getTaskById(first.id))!.workflowRunStepId).toBeFalsy();
+
+    await waitForQueuedRetry(runId);
+    startRetryPoller(registry, 10);
+    const second = await waitForRedrive(step.id, first);
+    await waitFor(async () => {
+      const s = await synthesizeStep(runId);
+      return s.status === "waiting" ? s : null;
+    }, "step waiting on redriven task");
+    stopRetryPoller();
+
+    await failTask(second.id, SUPERSEDED_WORKFLOW_TASK_REASON);
+    const run = await waitFor(async () => {
+      const r = await getWorkflowRun(runId);
+      return r?.status === "failed" ? r : null;
+    }, "run failed via onNodeFailure:fail");
+    expect(run.error).toContain(SUPERSEDED_WORKFLOW_TASK_REASON);
+    const finalStep = await synthesizeStep(runId);
+    expect(finalStep.status).toBe("failed");
+    expect(finalStep.retryCount).toBe(1);
+    expect(finalStep.nextRetryAt).toBeFalsy();
+    expect((await getTaskByWorkflowRunStepId(step.id))!.id).toBe(second.id);
+  });
+
+  test("the redriven task completing continues the run", async () => {
+    const runId = await startRun({ onNodeFailure: "continue" });
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    await failTask(first.id, SUPERSEDED_WORKFLOW_TASK_REASON);
+    await waitForQueuedRetry(runId);
+    startRetryPoller(registry, 10);
+    const second = await waitForRedrive(step.id, first);
+    await waitFor(async () => {
+      const s = await synthesizeStep(runId);
+      return s.status === "waiting" ? s : null;
+    }, "step waiting on redriven task");
+    stopRetryPoller();
+
+    await completeTask(second.id, "synthesis done");
+    const run = await waitFor(async () => {
+      const r = await getWorkflowRun(runId);
+      return r?.status === "completed" ? r : null;
+    }, "run completed");
+    expect(run.status).toBe("completed");
+    const finalStep = await synthesizeStep(runId);
+    expect(JSON.stringify(finalStep.output)).not.toContain("[FAILED:");
+  });
+
+  test("explicit retry {maxRetries:0} opts out: the cut fails the run", async () => {
+    const runId = await startRun({ retry: { ...RETRY_ONCE, maxRetries: 0 } });
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    await failTask(first.id, SUPERSEDED_WORKFLOW_TASK_REASON);
+
+    const run = await waitFor(async () => {
+      const r = await getWorkflowRun(runId);
+      return r?.status === "failed" ? r : null;
+    }, "run failed");
+    expect(run.error).toContain(SUPERSEDED_WORKFLOW_TASK_REASON);
+    const failedStep = await synthesizeStep(runId);
+    expect(failedStep.retryCount).toBe(0);
+    expect(failedStep.nextRetryAt).toBeFalsy();
+    expect((await getTaskByWorkflowRunStepId(step.id))!.id).toBe(first.id);
+  });
+
+  test("the recovery sweep reads the cut from the task row", async () => {
+    const runId = await startRun({});
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    teardownResumeListener?.();
+    try {
+      await failTask(first.id, SUPERSEDED_WORKFLOW_TASK_REASON);
+      await new Promise((r) => setTimeout(r, 20));
+      await recoverIncompleteRuns(registry);
+    } finally {
+      teardownResumeListener = setupWorkflowResumeListener(workflowEventBus, registry);
+    }
+
+    const queued = await synthesizeStep(runId);
+    expect(queued.status).toBe("failed");
+    expect(queued.nextRetryAt).toBeTruthy();
+    expect(queued.retryCount).toBe(1);
+    expect((await getWorkflowRun(runId))!.status).toBe("waiting");
+  });
+});
+
 describe("recovery sweep holding a stale failed-task snapshot", () => {
   /**
    * Recovery snapshots task A as failed, then pauses. Meanwhile the live

package/src/tests/workflow-wait-recovery.test.ts

@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, spyOn, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import * as db from "../be/db";
 import {
@@ -13,6 +13,7 @@ import {
   getWorkflowRunStep,
   getWorkflowRunStepsByRunId,
   initDb,
+  resolveWaitState,
   updateWorkflowRun,
   updateWorkflowRunStep,
 } from "../be/db";
@@ -23,6 +24,10 @@ import { createExecutorRegistry } from "../workflows/executors/registry";
 import { recoverIncompleteRuns } from "../workflows/recovery";
 
 const TEST_DB_PATH = "./test-workflow-wait-recovery.sqlite";
+const templateGlobals = globalThis as typeof globalThis & {
+  __testMigrationTemplate?: Uint8Array;
+};
+let savedTemplate: Uint8Array | undefined;
 
 const eventBus = new InProcessEventBus();
 const deps: ExecutorDependencies = {
@@ -42,7 +47,52 @@ async function makeWorkflow(name: string, def: WorkflowDefinition): Promise<Work
   return wf;
 }
 
+async function makeResolvedWait(
+  mode: "time" | "event",
+  status: "fired" | "timeout",
+  nextPort: string,
+) {
+  const wf = await makeWorkflow("wait-recovery-resolved", {
+    nodes: [
+      {
+        id: "w1",
+        type: "wait",
+        config:
+          mode === "time"
+            ? { mode, durationMs: 60_000 }
+            : { mode, eventName: "saved.signal", timeoutMs: 60_000 },
+        next: { [nextPort]: "done" },
+      },
+      { id: "done", type: "notify", config: { channel: "swarm", template: "recovered" } },
+    ],
+  });
+  const run = await createWorkflowRun({ id: crypto.randomUUID(), workflowId: wf.id });
+  await updateWorkflowRun(run.id, { status: "waiting" });
+  const step = await createWorkflowRunStep({
+    id: crypto.randomUUID(),
+    runId: run.id,
+    nodeId: "w1",
+    nodeType: "wait",
+  });
+  await updateWorkflowRunStep(step.id, { status: "waiting" });
+  const future = new Date(Date.now() + 60_000).toISOString();
+  const wait = await createWaitState({
+    id: crypto.randomUUID(),
+    workflowRunId: run.id,
+    workflowRunStepId: step.id,
+    mode,
+    ...(mode === "time" ? { wakeUpAt: future } : { eventName: "saved.signal", expiresAt: future }),
+  });
+  const payload = mode === "event" && status === "fired" ? { signal: "saved", ok: true } : null;
+  const resolution = await resolveWaitState(wait.id, { status, firedPayload: payload });
+  expect(resolution.updated).toBe(true);
+  return { run, step, wait, payload, resolution };
+}
+
 beforeAll(async () => {
+  // Use a file-backed DB so restart cases retain their committed wait resolutions.
+  savedTemplate = templateGlobals.__testMigrationTemplate;
+  templateGlobals.__testMigrationTemplate = undefined;
   try {
     await unlink(TEST_DB_PATH);
   } catch {
@@ -60,12 +110,76 @@ afterAll(async () => {
     }
   }
   closeDb();
+  templateGlobals.__testMigrationTemplate = savedTemplate;
   for (const suffix of ["", "-wal", "-shm"]) {
     await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => {});
   }
 });
 
 describe("WaitExecutor — recovery on startup", () => {
+  test.each([
+    ["time", "fired", "default"],
+    ["event", "fired", "event"],
+    ["event", "timeout", "timeout"],
+  ] as const)("recovers a persisted %s/%s resolution after restart via '%s' exactly once", async (mode, status, nextPort) => {
+    const registry = createExecutorRegistry(deps);
+    const { run, step, wait, payload, resolution } = await makeResolvedWait(mode, status, nextPort);
+
+    // Reopen after the resolution commits, before the waiting step is checkpointed.
+    closeDb();
+    initDb(TEST_DB_PATH);
+    expect((await getWorkflowRunStep(step.id))?.status).toBe("waiting");
+    expect((await getWaitStateByStepId(step.id))?.status).toBe(status);
+    await Promise.all([recoverIncompleteRuns(registry), recoverIncompleteRuns(registry)]);
+
+    const recoveredStep = await getWorkflowRunStep(step.id);
+    expect(recoveredStep?.status).toBe("completed");
+    expect(recoveredStep?.nextPort).toBe(nextPort);
+    expect(recoveredStep?.output).toEqual({
+      waitId: wait.id,
+      mode,
+      firedAt: resolution.row!.resolvedAt,
+      payload,
+    });
+    expect(await getWaitStateByStepId(step.id)).toEqual(resolution.row);
+    expect((await getWorkflowRun(run.id))?.status).toBe("completed");
+    const doneSteps = (await getWorkflowRunStepsByRunId(run.id)).filter((s) => s.nodeId === "done");
+    expect(doneSteps).toHaveLength(1);
+    expect(doneSteps[0]?.status).toBe("completed");
+
+    await recoverIncompleteRuns(registry);
+    expect((await getWorkflowRunStepsByRunId(run.id)).filter((s) => s.nodeId === "done")).toEqual(
+      doneSteps,
+    );
+    expect((await getWorkflowRun(run.id))?.status).toBe("completed");
+  });
+
+  test.each([
+    "completed",
+    "failed",
+    "cancelled",
+  ] as const)("does not reopen a %s run that becomes terminal during wait recovery", async (status) => {
+    const registry = createExecutorRegistry(deps);
+    const { run, step } = await makeResolvedWait("event", "fired", "event");
+    const getWorkflow = db.getWorkflow;
+    const snapshot = spyOn(db, "getWorkflow").mockImplementationOnce(async (id) => {
+      const workflow = await getWorkflow(id);
+      expect((await getWorkflowRun(run.id))?.status).toBe("waiting");
+      // A sibling can fail the run after the resume read, leaving this step waiting.
+      await updateWorkflowRun(run.id, { status });
+      return workflow;
+    });
+    try {
+      await recoverIncompleteRuns(registry);
+      expect(snapshot).toHaveBeenCalledTimes(1);
+      expect((await getWorkflowRun(run.id))?.status).toBe(status);
+      expect((await getWorkflowRunStep(step.id))?.status).toBe("waiting");
+      expect(await getWorkflowRunStepsByRunId(run.id)).toHaveLength(1);
+    } finally {
+      snapshot.mockRestore();
+    }
+  });
+
   test("server died while waiting: overdue time-mode wait recovers via 'default' port", async () => {
     const registry = createExecutorRegistry(deps);
 
@@ -170,9 +284,7 @@ describe("WaitExecutor — recovery on startup", () => {
     const doneCount1 = stepsAfter1.filter((s) => s.nodeId === "done").length;
     expect(doneCount1).toBe(1);
 
-    // Second recovery pass — wait_state is now 'fired' (case a in the
-    // recovery query). resumeWaitState's atomic update returns updated=false,
-    // so the step shouldn't re-run.
+    // Completed runs and steps are no longer eligible for recovery.
     await recoverIncompleteRuns(registry);
     const stepsAfter2 = await getWorkflowRunStepsByRunId(run.id);
     expect(stepsAfter2.filter((s) => s.nodeId === "done").length).toBe(1);

package/src/tools/app-action-run.ts

@@ -0,0 +1,63 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { runAppAction } from "../apps/action-runner";
+import { AppNameSchema } from "../apps/definition";
+import { appDefinitionNeedsRepair, getApp } from "../apps/store";
+import { getAgentById } from "../be/db";
+import { can } from "../rbac";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "./utils";
+
+export function registerAppActionRunTool(server: McpServer) {
+  createToolRegistrar(server)(
+    "app-action-run",
+    {
+      title: "Run an app action",
+      description:
+        "Run a declared app action as an agent. Scripts and extensions cannot invoke this tool.",
+      // An action runs a script, a sync, or a task: it can write rows and reach external sources.
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+      rbac: { permission: "app.use" },
+      inputSchema: z.object({
+        appId: z.string().min(1),
+        action: AppNameSchema,
+        input: z.record(z.string(), z.unknown()).optional(),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        ok: z.boolean().optional(),
+        result: z.unknown().optional(),
+        stdout: z.string().optional(),
+        error: z.string().optional(),
+        durationMs: z.number().optional(),
+        taskId: z.string().optional(),
+        status: z.string().optional(),
+      }),
+    },
+    async ({ appId, action, input }, info) => {
+      if (info.callOrigin === "script-sdk" || info.callOrigin === "extension")
+        return toolErr("Scripts and extensions cannot run app actions.");
+      if (!info.agentId) return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
+      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 } });
+      const output = await runAppAction({
+        app,
+        name: action,
+        input,
+        actor: `agent:${info.agentId}`,
+        caller: { kind: "agent", id: info.agentId, ...(agent?.name ? { name: agent.name } : {}) },
+      });
+      if (output.status !== 200)
+        return toolErr(output.body.error ?? "Action failed.", { data: output.body });
+      return toolOk("Action invoked.", { data: output.body });
+    },
+  );
+}

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/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"),
       }),