@desplega.ai/agent-swarm 1.151.0 → 1.152.0

package/src/tests/reload-config.test.ts

@@ -227,6 +227,23 @@ describe("reload-config", () => {
     }
   });
 
+  test("stored lead activation gate cannot override the deployment at boot or reload", async () => {
+    const key = "EXTENSION_ALLOW_LEAD_ACTIVATION";
+    const original = process.env[key];
+    const rowId = await insertLegacyReservedRow(key, "true");
+    try {
+      process.env[key] = "false";
+      for (const override of [false, true]) {
+        expect(await loadGlobalConfigsIntoEnv(override)).not.toContain(key);
+        expect(process.env[key]).toBe("false");
+      }
+    } finally {
+      await deleteSwarmConfig(rowId);
+      if (original === undefined) delete process.env[key];
+      else process.env[key] = original;
+    }
+  });
+
   test("loadGlobalConfigsIntoEnv skips unreadable reserved secret rows before decrypting them", async () => {
     const id = await insertUnreadableReservedSecretRow("SECRETS_ENCRYPTION_KEY");
 

package/src/tests/scripts-only-gating.test.ts

@@ -17,6 +17,10 @@ import { listenOnFreePort } from "./test-net";
 
 const TEST_DB_PATH = "./test-scripts-only-gating.sqlite";
 const SCRIPT_TOOL_NAMES = [
+  "extension-delete",
+  "extension-enable",
+  "extension-disable",
+  "extension-activate-version",
   "extension-install",
   "extension-list",
   "get-script-run",

package/src/tests/slack-render-v2.test.ts

@@ -1789,7 +1789,7 @@ describe("Slack renderer v2", () => {
     expect(outcome?.finalizedAt).toBeDefined();
   });
 
-  test("keeps a deferral's human-facing line even when the agent already sent a slack-reply", async () => {
+  test("omits the deferral ETA even when the agent already sent a slack-reply", async () => {
     const lead = await createAgent({ name: "Deferring Lead", isLead: true, status: "idle" });
     const { channelId, threadTs } = uniqueSlackAddress("C_RENDER_DEFER_AFTER_REPLY");
     const ask = await createTaskExtended("defer after replying by hand", {
@@ -1814,10 +1814,32 @@ describe("Slack renderer v2", () => {
     await processSlackRenderV2();
 
     const started = calls.find((call) => call.method === "chat.startStream");
-    expect(started?.payload.markdown_text).toBe(`✅\n\n${deferralLine}`);
+    expect(started?.payload.markdown_text).toBe("✅\n\nPending: checking the new defer card");
+    expect(JSON.stringify(calls)).not.toContain("17:30:19");
+    expect(JSON.stringify(calls)).not.toContain("Deferred until");
+    expect((await getTaskById(ask.id))?.output).toBe(deferralLine);
     expect(started?.payload.markdown_text).not.toBe(`✅ ${lead.name} completed`);
   });
 
+  test("does not post an ETA-only deferral notice", async () => {
+    const { channelId, threadTs } = uniqueSlackAddress("C_ETA_ONLY");
+    const ask = await createTaskExtended("wait", {
+      source: "slack",
+      slackChannelId: channelId,
+      slackThreadTs: threadTs,
+    });
+    await startTask(ask.id);
+    await completeTask(
+      ask.id,
+      "Deferred until today 17:30 UTC ([12345678](https://example.com/schedules/12345678)) -> ",
+      { addTags: ["deferred"] },
+    );
+    calls.length = 0;
+    await processSlackRenderV2();
+    expect(calls.filter((call) => call.method === "chat.startStream")).toHaveLength(0);
+    expect(JSON.stringify(calls)).not.toContain("17:30");
+  });
+
   test("refreshes a stream started with stale content before finalizing it", async () => {
     const lead = await createAgent({ name: "Refresh Lead", isLead: true, status: "idle" });
     const { channelId, threadTs } = uniqueSlackAddress("C_RENDER_REFRESH_STALE");

package/src/tests/slack-task-output.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { slackTaskOutput } from "../slack/task-output";
+
+const task = {
+  status: "completed" as const,
+  tags: ["deferred"],
+  output:
+    "Deferred until tomorrow 17:30 UTC ([12345678](https://example.com/schedules/12345678)) -> check the build",
+};
+
+describe("Slack deferral output", () => {
+  test("keeps the pending work without the ETA or schedule link", () => {
+    expect(slackTaskOutput(task)).toBe("Pending: check the build");
+    expect(task.output).toContain("tomorrow 17:30 UTC");
+  });
+
+  test("removes an ETA-only line and preserves punctuation in the pending description", () => {
+    expect(slackTaskOutput({ ...task, output: task.output.replace("check the build", "") })).toBe(
+      "",
+    );
+    expect(slackTaskOutput({ ...task, output: `${task.output} (CI) -> deploy` })).toBe(
+      "Pending: check the build (CI) -> deploy",
+    );
+  });
+
+  test("preserves final continuation results even with inherited deferred tags", () => {
+    expect(slackTaskOutput({ ...task, output: "Build passed." })).toBe("Build passed.");
+  });
+
+  test("preserves schema output and non-deferral output verbatim", () => {
+    expect(slackTaskOutput({ ...task, outputSchema: { type: "string" } })).toBe(task.output);
+    expect(slackTaskOutput({ ...task, tags: [] })).toBe(task.output);
+    expect(slackTaskOutput({ ...task, status: "in_progress" })).toBe(task.output);
+    expect(slackTaskOutput({ ...task, output: undefined })).toBeUndefined();
+  });
+});

package/src/tests/store-progress-attachments-handler.test.ts

@@ -17,7 +17,7 @@
  *      org/drive and credentials
  *   4. missing files and wrong drives both block attachment + task writes
  */
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, spyOn, test } from "bun:test";
 import crypto from "node:crypto";
 import { unlink } from "node:fs/promises";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -34,6 +34,7 @@ import {
   upsertSwarmConfig,
 } from "../be/db";
 import { registerStoreProgressTool } from "../tools/store-progress";
+import malformedOutput from "./fixtures/store-progress-malformed-output.json";
 
 const TEST_DB_PATH = "./test-store-progress-attachments-handler.sqlite";
 const ORIGINAL_FETCH = globalThis.fetch;
@@ -137,6 +138,104 @@ describe("store-progress handler — attachments insert path", () => {
     };
   }
 
+  test("salvages the literal 59811b57 output and registers both URL attachments", async () => {
+    const task = await createTaskExtended("salvage leaked tool parameters", { agentId });
+    await startTask(task.id);
+    const result = (await buildServer().handler(
+      { taskId: task.id, status: "completed", output: malformedOutput.output },
+      buildMeta(),
+    )) as StoreProgressResult;
+
+    expect(result.structuredContent.success).toBe(true);
+    const saved = await getTaskById(task.id);
+    expect(saved?.output).toBe(malformedOutput.output.split("</output>")[0]);
+    expect(saved?.output?.endsWith("reposted clean.")).toBe(true);
+    const attachments = await getTaskAttachments(task.id);
+    expect(attachments).toHaveLength(2);
+    expect(attachments.every((a) => a.kind === "url")).toBe(true);
+    expect(attachments.map((a) => a.url).sort()).toEqual([
+      "https://api.desplega.agent-swarm.dev/p/556b11781dbb40bf9b1eb1b3315adae6",
+      "https://x.com/desplegalabs/status/2100595056939827590",
+    ]);
+    expect(attachments.find((a) => a.isPrimary)?.name).toBe("X reply in the Jev thread");
+  });
+
+  test("preserves clean output byte-for-byte", async () => {
+    const output = "The output is ready: 2 < 3.\n  Keep this whitespace.  ";
+    const task = await createTaskExtended("clean output control", { agentId });
+    await startTask(task.id);
+    const result = (await buildServer().handler(
+      { taskId: task.id, status: "completed", output },
+      buildMeta(),
+    )) as StoreProgressResult;
+    expect(result.structuredContent.success).toBe(true);
+    expect((await getTaskById(task.id))?.output).toBe(output);
+    expect(await getTaskAttachments(task.id)).toHaveLength(0);
+  });
+
+  test.each([
+    ["invalid JSON", '</output>\n<parameter name="attachments">[broken'],
+    ["invalid attachment schema", '</output><parameter name="attachments">[{"kind":"url"}]'],
+    ["unknown parameter", '</output><parameter name="status">"failed"'],
+    ["alternate closing tag", '</parameter>\n<parameter name="progress">Not JSON'],
+    ["bare opener", '<parameter name="progress">Not JSON'],
+    ["non-array JSON", '</output><parameter name="attachments">null'],
+  ])("strips %s without losing the clean result", async (_name, tail) => {
+    const task = await createTaskExtended("unrecoverable tail", { agentId });
+    await startTask(task.id);
+    const warning = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const result = (await buildServer().handler(
+        { taskId: task.id, status: "completed", output: `Clean result.${tail}` },
+        buildMeta(),
+      )) as StoreProgressResult;
+      expect(result.structuredContent.success).toBe(true);
+      expect((await getTaskById(task.id))?.output).toBe("Clean result.");
+      expect((await getTaskById(task.id))?.status).toBe("completed");
+      expect(await getTaskAttachments(task.id)).toHaveLength(0);
+      expect(warning).toHaveBeenCalledTimes(1);
+      expect(warning.mock.calls[0]?.[0]).not.toContain(tail);
+    } finally {
+      warning.mockRestore();
+    }
+  });
+
+  test("appends recovered pointers to explicit attachments through the normal dedupe path", async () => {
+    const task = await createTaskExtended("mixed explicit and leaked attachments", { agentId });
+    await startTask(task.id);
+    const attachment = { kind: "url", name: "link", url: "https://example.com/link" };
+    const result = (await buildServer().handler(
+      {
+        taskId: task.id,
+        status: "completed",
+        output: `Done.<parameter name="attachments">${JSON.stringify([attachment])}</parameter>`,
+        attachments: [attachment],
+      },
+      buildMeta(),
+    )) as StoreProgressResult;
+    expect(result.structuredContent.success).toBe(true);
+    expect((await getTaskById(task.id))?.output).toBe("Done.");
+    expect(await getTaskAttachments(task.id)).toHaveLength(1);
+  });
+
+  test("recovered agent-fs pointers still require ordinary scope verification", async () => {
+    const task = await createTaskExtended("verify recovered pointer", { agentId });
+    await startTask(task.id);
+    const result = (await buildServer().handler(
+      {
+        taskId: task.id,
+        status: "completed",
+        output:
+          'Done.</output><parameter name="attachments">[{"kind":"agent-fs","name":"missing.md","path":"/missing.md"}]',
+      },
+      buildMeta(),
+    )) as StoreProgressResult;
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("both orgId and driveId must resolve");
+    expect((await getTaskById(task.id))?.status).toBe("in_progress");
+    expect(await getTaskAttachments(task.id)).toHaveLength(0);
+  });
+
   test("inserts attachment row on an in-progress task (baseline)", async () => {
     const task = await createTaskExtended("handler in-progress baseline", {
       agentId,

package/src/tests/swarm-config-reserved-keys.test.ts

@@ -134,7 +134,12 @@ describe("swarm-config reserved keys guard", () => {
     await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
   });
 
-  for (const key of ["CORS_ALLOW_ANY_ORIGIN", "cors_allow_any_origin"]) {
+  for (const key of [
+    "CORS_ALLOW_ANY_ORIGIN",
+    "cors_allow_any_origin",
+    "EXTENSION_ALLOW_LEAD_ACTIVATION",
+    "extension_allow_lead_activation",
+  ]) {
     test(`rejects deployment-only ${key} through DB, HTTP, and MCP`, async () => {
       const config = { scope: "global" as const, key, value: "true" };
       await expect(upsertSwarmConfig(config)).rejects.toThrow(EXPECTED_MESSAGE(key));

package/src/tests/tool-annotations.test.ts

@@ -378,7 +378,7 @@ describe("Tool Annotations & Classification", () => {
     // Includes 11 skill tools, 7 MCP server tools, reusable script tools, and the
     // native Kapso/WhatsApp tools (register/unregister number + send/reply message).
     expect(count).toBeGreaterThanOrEqual(45);
-    expect(count).toBeLessThanOrEqual(143);
+    expect(count).toBeLessThanOrEqual(147);
   });
 
   test("core tools are fewer than deferred tools", () => {

package/src/tools/extension-activate-version.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const registerExtensionActivateVersionTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-activate-version",
+    {
+      title: "Extension Activate Version",
+      description:
+        "Activate a stored extension version, reloading it if enabled. Requires a lead, operator, or dashboard user.",
+      annotations: { openWorldHint: false },
+      inputSchema: z
+        .object({
+          id: z.string().uuid().describe("Installed extension ID from extension-list."),
+          version: z.number().int().min(1).describe("Stored version number to activate."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "POST",
+        path: `/api/extensions/${args.id}/activate-version`,
+        body: { version: args.version },
+        requestInfo,
+        success: (data) =>
+          toolOk("Extension activated.", {
+            data: coerceExtensionSummary((data as { extension?: unknown }).extension),
+          }),
+      }),
+  );
+};

package/src/tools/extension-common.ts

@@ -26,6 +26,7 @@ export const extensionToolOutputSchema = swarmToolOutputSchema({
   priority: z.number().optional(),
   consecutiveFailures: z.number().optional(),
   contentDeduped: z.boolean().optional(),
+  deleted: z.boolean().optional(),
   extensions: z.array(extensionListItemSchema).optional(),
 });
 
@@ -61,7 +62,7 @@ function renderDiagnostics(data: unknown): string | undefined {
 }
 
 export async function proxyExtensionsApi<T>(args: {
-  method: "GET" | "POST";
+  method: "GET" | "POST" | "DELETE";
   path: string;
   body?: unknown;
   requestInfo: RequestInfo;

package/src/tools/extension-delete.ts

@@ -0,0 +1,29 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import { extensionToolOutputSchema, proxyExtensionsApi } from "./extension-common";
+
+export const registerExtensionDeleteTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-delete",
+    {
+      title: "Extension Delete",
+      description:
+        "Uninstall a disabled extension and delete its stored history. Disable it first with extension-disable. Requires a lead, operator, or dashboard user.",
+      annotations: { openWorldHint: false, destructiveHint: true },
+      inputSchema: z
+        .object({
+          id: z.string().uuid().describe("Installed extension ID from extension-list."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "DELETE",
+        path: `/api/extensions/${args.id}`,
+        requestInfo,
+        success: () => toolOk("Extension deleted.", { data: { id: args.id, deleted: true } }),
+      }),
+  );
+};

package/src/tools/extension-disable.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const registerExtensionDisableTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-disable",
+    {
+      title: "Extension Disable",
+      description:
+        "Unload and disable an installed extension. Requires a lead, operator, or dashboard user.",
+      annotations: { openWorldHint: false },
+      inputSchema: z
+        .object({
+          id: z.string().uuid().describe("Installed extension ID from extension-list."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "POST",
+        path: `/api/extensions/${args.id}/disable`,
+        requestInfo,
+        success: (data) =>
+          toolOk("Extension disabled.", {
+            data: coerceExtensionSummary((data as { extension?: unknown }).extension),
+          }),
+      }),
+  );
+};

package/src/tools/extension-enable.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const registerExtensionEnableTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-enable",
+    {
+      title: "Extension Enable",
+      description:
+        "Load and enable an installed extension. Requires a lead, operator, or dashboard user.",
+      annotations: { openWorldHint: false },
+      inputSchema: z
+        .object({
+          id: z.string().uuid().describe("Installed extension ID from extension-list."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "POST",
+        path: `/api/extensions/${args.id}/enable`,
+        requestInfo,
+        success: (data) =>
+          toolOk("Extension enabled.", {
+            data: coerceExtensionSummary((data as { extension?: unknown }).extension),
+          }),
+      }),
+  );
+};

package/src/tools/extension-install.ts

@@ -9,7 +9,7 @@ import {
 } from "./extension-common";
 
 export const EXTENSION_INSTALL_DESCRIPTION =
-  "Validate and store a TypeScript extension bundle (manifest plus a files map with one hooks.ts). Fetch the hook contract first: GET /api/extensions/type-defs returns swarm-extension.d.ts with every event and modify shape. The extension remains disabled until an operator enables it.";
+  "Validate and store a TypeScript extension bundle (manifest plus a files map with one hooks.ts). Fetch the hook contract first: GET /api/extensions/type-defs returns swarm-extension.d.ts with every event and modify shape. The extension remains disabled until a lead, operator, or dashboard user enables it with extension-enable.";
 
 function extensionInstallResult(data: unknown, fallbackName: string) {
   const body = data as {
@@ -21,7 +21,7 @@ function extensionInstallResult(data: unknown, fallbackName: string) {
   const version = typeof extension.version === "number" ? ` v${extension.version}` : "";
   const deduped = body.contentDeduped === true ? " Content was unchanged." : "";
   const enableInstruction =
-    "An operator must enable it from the dashboard or `POST /api/extensions/{id}/enable`.";
+    "A lead, operator, or dashboard user can enable it with `extension-enable` or `POST /api/extensions/{id}/enable`.";
 
   return toolOk(`Extension \`${name}\`${version} installed.${deduped} ${enableInstruction}`, {
     data: {

package/src/tools/store-progress.ts

@@ -167,6 +167,36 @@ export const registerStoreProgressTool = (server: McpServer) => {
           ? requestedStatus
           : undefined;
 
+      // Stock Claude occasionally puts the next tool parameter inside output.
+      // Strip the leaked tail before validation/persistence; recovered pointers
+      // must still pass the ordinary attachment schema and verification below.
+      const leakedParameter = output?.match(
+        /(?:<\/(?:output|parameter)>\s*)?<parameter name="([a-zA-Z_]+)">\s*([\s\S]*)$/,
+      );
+      if (leakedParameter) {
+        output = output?.slice(0, leakedParameter.index);
+        let recovered = false;
+        if (leakedParameter[1] === "attachments") {
+          try {
+            const parsed = z
+              .array(AttachmentInputSchema)
+              .max(20)
+              .safeParse(JSON.parse(leakedParameter[2]!.replace(/\s*<\/parameter>\s*$/, "")));
+            if (parsed.success && (attachments?.length ?? 0) + parsed.data.length <= 20) {
+              attachments = [...(attachments ?? []), ...parsed.data];
+              recovered = true;
+            }
+          } catch {
+            // Malformed JSON must not prevent saving the cleaned task result.
+          }
+        }
+        if (!recovered) {
+          console.warn(
+            `[store-progress] Stripped malformed output tail for task ${taskId}; parameter ${leakedParameter[1]} was not recovered.`,
+          );
+        }
+      }
+
       // Verify agent-fs pointers before opening the write transaction. The
       // registering agent's resolved config selects both credentials and the
       // exact org/drive; never let the provider fall back to a personal drive.

package/src/tools/tool-config.ts

@@ -197,13 +197,17 @@ export const DEFERRED_TOOLS = new Set([
   "room-reset",
   "room-decode",
 
-  // Reusable scripts and extensions (8)
+  // Reusable scripts and extensions (12)
   "script-upsert",
   "script-delete",
   "script-apis",
   "launch-script-run",
   "get-script-run",
   "list-script-runs",
+  "extension-delete",
+  "extension-enable",
+  "extension-disable",
+  "extension-activate-version",
   "extension-install",
   "extension-list",
 

package/templates/skills/agent-browser/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: agent-browser
+description: "Drive a real browser with the agent-browser CLI (headless Chromium over CDP). Use for any browser task: verifying a UI change, taking a screenshot, walking a web page, filling a form, extracting page text, reproducing a frontend bug, or attaching UI evidence to a PR, issue, Linear comment, or Slack thread. Starts with a `command -v agent-browser` check and falls back to manual QA on the slim worker image. Screenshots are shared through agent-fs signed URLs. This is the only browser automation tool; do not use qa-use."
+---
+
+# agent-browser
+
+`agent-browser` (vercel-labs) is the swarm's browser-automation CLI. It drives a headless Chromium over CDP and returns accessibility-tree snapshots with compact `@eN` refs. Use it for any browser task: verify a UI change, take a screenshot, walk a page, fill a form, extract page text, reproduce a frontend bug, or attach UI evidence to a PR, issue, Linear comment, or Slack thread.
+
+Do not use `qa-use`. It is not installed in the worker image any more.
+
+## Step 0: check that the CLI is present
+
+The full worker image (`agent-swarm-worker:latest`) ships `agent-browser` and a headless Chromium. The slim image (`:slim`) has neither. The first command of any browser work is:
+
+```bash
+command -v agent-browser
+```
+
+If it prints nothing, you are on the slim image. Say so in your progress report ("agent-browser is not available on this worker image") and fall back to manual QA: write the exact steps a human should run and mark the browser test cases as **Blocked**, not failed. Do not install a browser or the CLI yourself.
+
+## Step 1: load the version-matched guide
+
+The CLI bundles its own usage guide. Load it once per task before the first browser command. Do not guess flags from memory.
+
+```bash
+agent-browser skills get core          # overview + common patterns
+agent-browser skills get core --full   # adds the full command reference
+agent-browser skills list              # specialized guides (dogfood, electron, slack, ...)
+```
+
+## Step 2: the core loop
+
+```bash
+agent-browser open <url>
+agent-browser snapshot -i              # accessibility tree, interactive elements only, @eN refs
+agent-browser click @e12               # act on refs from the snapshot
+agent-browser fill @e7 "text"
+agent-browser screenshot /tmp/<name>.png
+agent-browser close
+```
+
+- Re-run `snapshot` after every navigation or state change. Refs are only valid for the snapshot that produced them.
+- Run one browser session at a time. Call `store-progress` between page batches so the heartbeat watchdog sees you.
+- The browser is headless. Local servers inside the worker container are reachable at `http://localhost:<port>`.
+- The image launches Chromium with `--no-sandbox,--disable-dev-shm-usage` through `AGENT_BROWSER_ARGS`. If you pass your own `--args`, include `--no-sandbox` again or Chrome will not start.
+
+## Recording
+
+Default: record with `--cursor`, drive every supported pointer action (`click`, `mouse move`, `drag`) with `--human`, and ship the **1.5x video**. Keep the 1x original only if a reviewer asks for it. Human pointer movement follows an eased curve; use `--seed <n>` on `mouse move` to make the take reproducible instead of using a bare move.
+
+Open the page first, then record the interaction:
+
+```bash
+agent-browser record start ./in.mp4 --cursor
+agent-browser snapshot -i
+agent-browser mouse move 600 400 --human --seed 42 --duration 1400
+agent-browser click @e3 --human          # use a ref from the current snapshot
+# Perform the remaining QA steps; use --human for drag actions too.
+agent-browser record stop
+ffmpeg -y -i in.mp4 -filter:v "setpts=PTS/1.5,fps=30" -an \
+  -c:v libx264 -preset veryfast -crf 23 -pix_fmt yuv420p out-1.5x.mp4
+```
+
+Speed-up is a post-process step: `record start` has no speed or human flag. Keep `fps=30` to preserve a steady 30 fps output rather than uneven frame drops at an inferred rate. `-an` disables audio because agent-browser recordings carry no audio track. The worker ships only `ffmpeg`, not `ffprobe`; inspect duration with `ffmpeg -i out-1.5x.mp4 2>&1 | grep Duration`.
+
+Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Upload the 1.5x file through the same agent-fs QA path and signed-URL steps as screenshots below, and link it in the PR body.
+
+## Step 3: share the screenshot through agent-fs
+
+Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention and share the signed URL. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
+
+```bash
+agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
+  --file /tmp/<name>.png -m "<what it shows>"
+agent-fs stat thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json        # confirm size > 0
+agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json  # 24h default, --expires-in up to 7d
+```
+
+- Embed the URL as `![caption](<url>)` in the PR body, review comment, Linear comment, or Slack message.
+- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the signed URL in the progress text.
+- If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
+
+The `artifacts` skill holds the full agent-fs recipe and the naming conventions.

package/templates/skills/agent-browser/content.md

@@ -40,6 +40,27 @@ agent-browser close
 - The browser is headless. Local servers inside the worker container are reachable at `http://localhost:<port>`.
 - The image launches Chromium with `--no-sandbox,--disable-dev-shm-usage` through `AGENT_BROWSER_ARGS`. If you pass your own `--args`, include `--no-sandbox` again or Chrome will not start.
 
+## Recording
+
+Default: record with `--cursor`, drive every supported pointer action (`click`, `mouse move`, `drag`) with `--human`, and ship the **1.5x video**. Keep the 1x original only if a reviewer asks for it. Human pointer movement follows an eased curve; use `--seed <n>` on `mouse move` to make the take reproducible instead of using a bare move.
+
+Open the page first, then record the interaction:
+
+```bash
+agent-browser record start ./in.mp4 --cursor
+agent-browser snapshot -i
+agent-browser mouse move 600 400 --human --seed 42 --duration 1400
+agent-browser click @e3 --human          # use a ref from the current snapshot
+# Perform the remaining QA steps; use --human for drag actions too.
+agent-browser record stop
+ffmpeg -y -i in.mp4 -filter:v "setpts=PTS/1.5,fps=30" -an \
+  -c:v libx264 -preset veryfast -crf 23 -pix_fmt yuv420p out-1.5x.mp4
+```
+
+Speed-up is a post-process step: `record start` has no speed or human flag. Keep `fps=30` to preserve a steady 30 fps output rather than uneven frame drops at an inferred rate. `-an` disables audio because agent-browser recordings carry no audio track. The worker ships only `ffmpeg`, not `ffprobe`; inspect duration with `ffmpeg -i out-1.5x.mp4 2>&1 | grep Duration`.
+
+Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Upload the 1.5x file through the same agent-fs QA path and signed-URL steps as screenshots below, and link it in the PR body.
+
 ## Step 3: share the screenshot through agent-fs
 
 Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention and share the signed URL. `--file` is binary-safe. `--content` is text-only and mangles PNGs.