@desplega.ai/agent-swarm 1.149.1 → 1.151.0

package/src/slack/work-objects.test.ts

@@ -0,0 +1,252 @@
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
+import type { SlackEventMiddlewareArgs } from "@slack/bolt";
+import type { EntityPresentDetailsArguments } from "@slack/web-api";
+import * as db from "../be/db";
+import { AgentTaskSchema } from "../types";
+import * as handlers from "./handlers";
+import { registerWorkObjectHandlers } from "./work-objects";
+
+const taskId = "11111111-2222-4333-8444-555555555555";
+const task = AgentTaskSchema.parse({
+  id: taskId,
+  key: `shared/task:${taskId}/`,
+  agentId: null,
+  task: "Implement Work Object details",
+  title: "Slack flexpane support",
+  status: "completed",
+  output: "Implemented and tested.",
+  createdAt: "2026-09-15T09:00:00.000Z",
+  lastUpdatedAt: "2026-09-15T10:00:00.000Z",
+  slackChannelId: "C_TASK",
+});
+
+type DetailsEvent = SlackEventMiddlewareArgs<"entity_details_requested">["event"];
+const event: DetailsEvent = {
+  type: "entity_details_requested",
+  user: "U_ALLOWED",
+  trigger_id: "trigger-123",
+  external_ref: { type: "task", id: taskId },
+  entity_url: `https://swarm.example/tasks/${taskId}`,
+  link: { url: `https://swarm.example/tasks/${taskId}`, domain: "swarm.example" },
+  user_locale: "en-US",
+  event_ts: "1757923200.000001",
+  channel: "C_TASK",
+};
+
+describe("Work Object details handler", () => {
+  const originalFlag = process.env.SLACK_WORK_OBJECTS_ENABLED;
+  const originalAppUrl = process.env.APP_URL;
+  const presentDetails = mock(async (_args: EntityPresentDetailsArguments) => ({ ok: true }));
+  const client = { entity: { presentDetails } };
+  const logger = { error: mock(() => {}) };
+  let listener: (args: {
+    event: DetailsEvent;
+    client: typeof client;
+    logger: typeof logger;
+  }) => Promise<void>;
+  let getTask: ReturnType<typeof spyOn<typeof db, "getTaskById">>;
+  let getAgent: ReturnType<typeof spyOn<typeof db, "getAgentById">>;
+  let userAllowed: ReturnType<typeof spyOn<typeof handlers, "isUserAllowed">>;
+
+  beforeEach(() => {
+    process.env.SLACK_WORK_OBJECTS_ENABLED = "true";
+    process.env.APP_URL = "https://swarm.example";
+    getTask = spyOn(db, "getTaskById").mockResolvedValue(task);
+    getAgent = spyOn(db, "getAgentById").mockResolvedValue(null);
+    userAllowed = spyOn(handlers, "isUserAllowed").mockResolvedValue(true);
+    presentDetails.mockReset();
+    presentDetails.mockResolvedValue({ ok: true });
+    logger.error.mockClear();
+    registerWorkObjectHandlers({
+      event: (name: string, callback: typeof listener) => {
+        expect(name).toBe("entity_details_requested");
+        listener = callback;
+      },
+    } as never);
+  });
+
+  afterEach(() => {
+    getTask.mockRestore();
+    getAgent.mockRestore();
+    userAllowed.mockRestore();
+    if (originalFlag === undefined) delete process.env.SLACK_WORK_OBJECTS_ENABLED;
+    else process.env.SLACK_WORK_OBJECTS_ENABLED = originalFlag;
+    if (originalAppUrl === undefined) delete process.env.APP_URL;
+    else process.env.APP_URL = originalAppUrl;
+  });
+
+  async function request(overrides: Partial<DetailsEvent> = {}) {
+    await listener({ event: { ...event, ...overrides }, client, logger });
+  }
+
+  for (const flag of [undefined, "false", "0", "typo"]) {
+    test(`does no work when flag is ${flag}`, async () => {
+      if (flag === undefined) delete process.env.SLACK_WORK_OBJECTS_ENABLED;
+      else process.env.SLACK_WORK_OBJECTS_ENABLED = flag;
+      await request();
+      expect(getTask).not.toHaveBeenCalled();
+      expect(userAllowed).not.toHaveBeenCalled();
+      expect(presentDetails).not.toHaveBeenCalled();
+    });
+  }
+
+  test("responds with current task data and the requesting trigger", async () => {
+    await request();
+    expect(presentDetails).toHaveBeenCalledTimes(1);
+    const response = presentDetails.mock.calls[0]?.[0];
+    expect(response?.trigger_id).toBe(event.trigger_id);
+    expect(response?.metadata).toMatchObject({
+      entity_type: "slack#/entities/task",
+      external_ref: event.external_ref,
+      url: event.entity_url,
+      entity_payload: {
+        attributes: { title: { text: task.title }, product_name: "Agent Swarm" },
+        fields: {
+          description: { value: task.task },
+          status: { value: "completed" },
+          assignee: { value: "Unassigned" },
+        },
+        custom_fields: [{ key: "result", label: "Result", value: task.output }],
+      },
+    });
+    expect(response?.metadata).not.toHaveProperty("entities");
+    expect(response?.metadata).not.toHaveProperty("app_unfurl_url");
+    expect(response).not.toHaveProperty("error");
+    expect(userAllowed).toHaveBeenCalledWith(client, event.user);
+    expect(getTask).toHaveBeenCalledWith(taskId);
+  });
+
+  test("reloads the task for each refresh and accepts 1 as the flag", async () => {
+    process.env.SLACK_WORK_OBJECTS_ENABLED = "1";
+    await request();
+    getTask.mockResolvedValue({
+      ...task,
+      status: "in_progress",
+      output: undefined,
+      progress: "Testing",
+    });
+    await request({ trigger_id: "refresh-trigger", app_unfurl_url: event.entity_url });
+    expect(getTask).toHaveBeenCalledTimes(2);
+    expect(presentDetails.mock.calls[1]?.[0]).toMatchObject({
+      trigger_id: "refresh-trigger",
+      metadata: {
+        entity_payload: {
+          fields: { status: { value: "in_progress" } },
+          custom_fields: [{ label: "Progress", value: "Testing" }],
+        },
+      },
+    });
+  });
+
+  test("shows failures and bounds long task text", async () => {
+    getTask.mockResolvedValue({
+      ...task,
+      title: undefined,
+      task: "x".repeat(10000),
+      status: "failed",
+      output: undefined,
+      failureReason: "y".repeat(10000),
+    });
+    await request();
+    const payload = presentDetails.mock.calls[0]?.[0].metadata?.entity_payload;
+    expect(payload?.attributes.title.text.length).toBe(200);
+    expect(payload?.fields).toMatchObject({ description: { value: `${"x".repeat(2799)}…` } });
+    expect(payload?.custom_fields?.[0]).toMatchObject({
+      label: "Failure",
+      value: `${"y".repeat(2799)}…`,
+    });
+  });
+
+  for (const type of ["file", "item", "content_item", "unknown", undefined]) {
+    test(`presents an error for unsupported reference type ${type}`, async () => {
+      await request({ external_ref: { id: taskId, type } });
+      expect(presentDetails).toHaveBeenCalledWith({
+        trigger_id: event.trigger_id,
+        error: {
+          status: "custom",
+          custom_title: "Work Object unavailable",
+          custom_message: "Agent Swarm does not support this Work Object reference.",
+        },
+      });
+      expect(getTask).not.toHaveBeenCalled();
+    });
+  }
+
+  test("presents an error when external_ref is absent or empty", async () => {
+    await request({ external_ref: undefined });
+    await request({ external_ref: { type: "task", id: "" } });
+    expect(presentDetails).toHaveBeenCalledTimes(2);
+    expect(getTask).not.toHaveBeenCalled();
+    for (const [response] of presentDetails.mock.calls)
+      expect(response.error?.status).toBe("custom");
+  });
+
+  test("presents not_found when the task was deleted", async () => {
+    getTask.mockResolvedValue(null);
+    await request();
+    expect(presentDetails).toHaveBeenCalledWith({
+      trigger_id: event.trigger_id,
+      error: { status: "not_found" },
+    });
+  });
+
+  test("denies filtered users before reading the task", async () => {
+    userAllowed.mockResolvedValue(false);
+    await request();
+    expect(getTask).not.toHaveBeenCalled();
+    expect(presentDetails).toHaveBeenCalledWith({
+      trigger_id: event.trigger_id,
+      error: { status: "restricted" },
+    });
+  });
+
+  for (const channel of [undefined, "C_OTHER"]) {
+    test(`does not disclose task details to channel ${channel}`, async () => {
+      await request({ channel });
+      expect(presentDetails).toHaveBeenCalledWith({
+        trigger_id: event.trigger_id,
+        error: { status: "restricted" },
+      });
+    });
+  }
+
+  test("does not disclose tasks without a Slack channel", async () => {
+    getTask.mockResolvedValue({ ...task, slackChannelId: undefined });
+    await request();
+    expect(presentDetails.mock.calls[0]?.[0].error?.status).toBe("restricted");
+  });
+
+  test("returns an error view when a task lookup fails", async () => {
+    getTask.mockRejectedValue(new Error("database unavailable"));
+    await request();
+    expect(presentDetails).toHaveBeenCalledWith({
+      trigger_id: event.trigger_id,
+      error: { status: "internal_error" },
+    });
+    expect(logger.error).toHaveBeenCalledTimes(1);
+  });
+
+  test("falls back to an error view when Slack rejects the metadata", async () => {
+    presentDetails.mockRejectedValueOnce(new Error("invalid_metadata"));
+    await request();
+    expect(presentDetails).toHaveBeenCalledTimes(2);
+    expect(presentDetails.mock.calls[1]?.[0]).toEqual({
+      trigger_id: event.trigger_id,
+      error: { status: "internal_error" },
+    });
+  });
+
+  test("logs a failed fallback without an unhandled rejection or retry loop", async () => {
+    presentDetails.mockRejectedValue(new Error("Slack unavailable"));
+    await request();
+    expect(presentDetails).toHaveBeenCalledTimes(2);
+    expect(logger.error).toHaveBeenCalledTimes(2);
+  });
+
+  test("logs rejection of an unknown object's error response", async () => {
+    presentDetails.mockRejectedValue(new Error("Slack unavailable"));
+    await request({ external_ref: undefined });
+    expect(presentDetails).toHaveBeenCalledTimes(1);
+    expect(logger.error).toHaveBeenCalledTimes(1);
+  });
+});

package/src/slack/work-objects.ts

@@ -0,0 +1,118 @@
+import type { App, SlackEventMiddlewareArgs } from "@slack/bolt";
+import type { EntityPresentDetailsArguments, WebClient } from "@slack/web-api";
+import { getAgentById, getTaskById } from "../be/db";
+import { isEnvFlagEnabled } from "../utils/env-flag";
+import { getTaskUrl } from "./blocks";
+import { isUserAllowed } from "./handlers";
+
+type DetailsEvent = SlackEventMiddlewareArgs<"entity_details_requested">["event"];
+type Details = Omit<EntityPresentDetailsArguments, "trigger_id" | "token">;
+
+function truncate(text: string, limit: number): string {
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+async function getDetails(event: DetailsEvent, client: WebClient): Promise<Details> {
+  const ref = event.external_ref;
+  // external_ref.type is our resource type, not Slack's entity_type. Never fetch event URLs.
+  if (ref?.type !== "task" || !ref.id) {
+    return {
+      error: {
+        status: "custom",
+        custom_title: "Work Object unavailable",
+        custom_message: "Agent Swarm does not support this Work Object reference.",
+      },
+    };
+  }
+
+  if (!event.user || !event.channel || !(await isUserAllowed(client, event.user))) {
+    return { error: { status: "restricted" } };
+  }
+
+  const task = await getTaskById(ref.id);
+  if (!task) return { error: { status: "not_found" } };
+
+  // A forwarded card must not expose a private task to another conversation.
+  if (task.slackChannelId !== event.channel) return { error: { status: "restricted" } };
+
+  const agent = task.agentId ? await getAgentById(task.agentId) : null;
+  const result = task.output || task.failureReason || task.progress;
+  return {
+    metadata: {
+      entity_type: "slack#/entities/task",
+      external_ref: ref,
+      url: getTaskUrl(task.id),
+      entity_payload: {
+        attributes: {
+          title: { text: truncate(task.title?.trim() || task.task, 200) },
+          display_id: task.id.slice(0, 8),
+          display_type: "Task",
+          product_name: "Agent Swarm",
+          metadata_last_modified: Math.floor(Date.parse(task.lastUpdatedAt) / 1000),
+        },
+        fields: {
+          description: { value: truncate(task.task, 2800), format: "markdown" },
+          status: { value: task.status },
+          assignee: { type: "string", value: agent?.name || task.agentId || "Unassigned" },
+          priority: { value: String(task.priority) },
+          date_created: { value: Math.floor(Date.parse(task.createdAt) / 1000) },
+          date_updated: { value: Math.floor(Date.parse(task.lastUpdatedAt) / 1000) },
+        },
+        ...(result
+          ? {
+              custom_fields: [
+                {
+                  key: "result",
+                  label: task.output ? "Result" : task.failureReason ? "Failure" : "Progress",
+                  type: "string",
+                  value: truncate(result, 2800),
+                  format: "markdown",
+                },
+              ],
+            }
+          : {}),
+        display_order: [
+          "status",
+          "assignee",
+          "priority",
+          "description",
+          ...(result ? ["result"] : []),
+          "date_created",
+          "date_updated",
+        ],
+      },
+    },
+  };
+}
+
+export function registerWorkObjectHandlers(app: App): void {
+  // Bolt acknowledges Events API deliveries; the flexpane needs a separate API response.
+  app.event("entity_details_requested", async ({ event, client, logger }) => {
+    if (!isEnvFlagEnabled("SLACK_WORK_OBJECTS_ENABLED", false)) return;
+
+    let details: Details;
+    try {
+      details = await getDetails(event, client);
+    } catch (error) {
+      logger.error("[Slack] Failed to load Work Object details", error);
+      details = { error: { status: "internal_error" } };
+    }
+
+    try {
+      await client.entity.presentDetails({ trigger_id: event.trigger_id, ...details });
+    } catch (error) {
+      logger.error("[Slack] Failed to present Work Object details", error);
+      // If Slack rejects the metadata, still try to replace the spinner with an error view.
+      if (details.metadata) {
+        try {
+          await client.entity.presentDetails({
+            trigger_id: event.trigger_id,
+            error: { status: "internal_error" },
+          });
+        } catch (fallbackError) {
+          logger.error("[Slack] Failed to present Work Object error", fallbackError);
+        }
+      }
+    }
+  });
+}

package/src/tasks/errors.ts

@@ -0,0 +1,9 @@
+export class TaskCreationBlockedError extends Error {
+  constructor(
+    readonly reason: string,
+    readonly extension: { id: string; name: string },
+  ) {
+    super(reason);
+    this.name = "TaskCreationBlockedError";
+  }
+}

package/src/tasks/sibling-awareness.ts

@@ -17,7 +17,10 @@ import {
   getAgentById,
   getInProgressTasksByContextKey,
 } from "../be/db";
+import { applyPreTaskCreate } from "../extensions/apply-task-create";
+import type { TaskCreateOrigin } from "../extensions/contract";
 import type { AgentTask } from "../types";
+import { TaskCreationBlockedError } from "./errors";
 import {
   pickResumeParent,
   prependSiblingBlock,
@@ -136,10 +139,41 @@ export async function withSiblingAwareness(
  * first. Use this from every ingress that has a `contextKey` so cross-ingress
  * sibling coordination is uniform without duplicating the wrapper boilerplate.
  */
+/** Final description and options after extension pre-hooks and sibling wiring. */
+export type PreparedTaskCreate = { description: string; options: CreateTaskOptions };
+
+/**
+ * Run the `pre.task.create` extension hooks and sibling-awareness wiring without
+ * inserting the task. Callers that must create the task inside a transaction call
+ * this first, outside the transaction, so extension hooks are not skipped by the
+ * dispatcher's `isInTransaction()` guard.
+ */
+export async function prepareTaskWithSiblingAwareness(
+  description: string,
+  options: CreateTaskOptions,
+  args: { origin?: TaskCreateOrigin } = {},
+): Promise<PreparedTaskCreate> {
+  const preCreate = await applyPreTaskCreate({
+    description,
+    options,
+    // Preserve the plan's REST default for callers without an explicit ingress origin.
+    origin: args.origin ?? "rest",
+  });
+  if (preCreate.kind === "blocked") {
+    throw new TaskCreationBlockedError(preCreate.reason, preCreate.extension);
+  }
+  return await withSiblingAwareness(preCreate.description, preCreate.options);
+}
+
 export async function createTaskWithSiblingAwareness(
   description: string,
   options: CreateTaskOptions,
+  args: { origin?: TaskCreateOrigin } = {},
 ): Promise<AgentTask> {
-  const { description: d, options: o } = await withSiblingAwareness(description, options);
+  const { description: d, options: o } = await prepareTaskWithSiblingAwareness(
+    description,
+    options,
+    args,
+  );
   return await createTaskExtended(d, o);
 }

package/src/tasks/worker-follow-up.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import {
   buildRoutingAffinityFromAgent,
   createLogEntry,
@@ -12,13 +13,32 @@ import {
   isAgentEligibleForTask,
 } from "../be/db";
 import { repointTrackerSyncBySwarmId } from "../be/db-queries/tracker";
+import { dispatchPre } from "../extensions/dispatcher";
 import { resolveTemplate } from "../prompts/resolver";
-import type { Agent, AgentTask, ResumeReason, RoutingAffinity, TaskAttachment } from "../types";
+import {
+  type Agent,
+  type AgentTask,
+  CreateTaskOptionsSchema,
+  type ResumeReason,
+  type RoutingAffinity,
+  type TaskAttachment,
+} from "../types";
 import { isEnvFlagEnabled } from "../utils/env-flag";
 import { taskAttachmentDisplayUrl } from "../utils/task-attachment-links";
+import { createTaskWithSiblingAwareness } from "./sibling-awareness";
 // Side-effect import: registers task lifecycle templates in the in-memory registry.
 import "../tools/templates";
 
+/** Runtime check for `pre.task.followUp` modifications (mirrors `TaskFollowUpModify`). */
+const TaskFollowUpModifySchema = CreateTaskOptionsSchema.pick({
+  agentId: true,
+  priority: true,
+  followUpConfig: true,
+})
+  .partial()
+  .extend({ description: z.string().trim().min(1).optional() })
+  .strict();
+
 /**
  * Liveness window (seconds) for considering a worker "online" enough to
  * pre-assign a resume task. Defaults to 30s; override via env. The worker
@@ -217,16 +237,49 @@ export async function createWorkerTaskFollowUp(args: {
     }
   }
 
-  return await createTaskExtended(followUpDescription, {
-    agentId: leadAgent.id,
-    routingReason: "skill",
-    source: "system",
-    taskType: "follow-up",
-    parentTaskId: task.id,
-    slackChannelId: task.slackChannelId,
-    slackThreadTs: task.slackThreadTs,
-    slackUserId: task.slackUserId,
-  });
+  const preFollowUp = await dispatchPre(
+    "pre.task.followUp",
+    {
+      completedTask: task,
+      status,
+      output,
+      failureReason,
+      workerAgentId: taskAgent.id,
+      leadAgentId: leadAgent.id,
+      summary: followUpDescription,
+    },
+    {
+      // A modification that violates the task schema (for example `priority: -1`)
+      // is attributed to the extension and ignored, so the follow-up is still created.
+      validateModify: (data) => {
+        const parsed = TaskFollowUpModifySchema.safeParse(data);
+        return parsed.success
+          ? { success: true, data: parsed.data }
+          : { success: false, error: new Error(parsed.error.message) };
+      },
+    },
+  );
+  if (preFollowUp.action === "block") return null;
+
+  const changes = preFollowUp.action === "modify" ? preFollowUp.data : {};
+  const followUpAgentId = changes.agentId === undefined ? leadAgent.id : changes.agentId;
+  return await createTaskWithSiblingAwareness(
+    changes.description ?? followUpDescription,
+    {
+      agentId: followUpAgentId,
+      routingReason: followUpAgentId ? "skill" : undefined,
+      routingSource: followUpAgentId ? "engine_default" : undefined,
+      source: "system",
+      taskType: "follow-up",
+      priority: changes.priority,
+      parentTaskId: task.id,
+      slackChannelId: task.slackChannelId,
+      slackThreadTs: task.slackThreadTs,
+      slackUserId: task.slackUserId,
+      followUpConfig: changes.followUpConfig,
+    },
+    { origin: "followUp" },
+  );
 }
 
 /** Result of `createResumeFollowUp`. */
@@ -431,6 +484,7 @@ export async function createResumeFollowUp(args: {
         : preferredAgentId === parent.agentId
           ? "continuity"
           : "reroute_fault",
+    routingSource: preferredAgentId === undefined ? undefined : "engine_default",
     creatorAgentId: parent.creatorAgentId,
     source: "system",
     taskType: "resume",
@@ -550,6 +604,7 @@ export async function createRerouteDecisionTask(args: {
   const created = await createTaskExtended(decision.text, {
     agentId: leadAgent.id,
     routingReason: "reroute_fault",
+    routingSource: "engine_default",
     creatorAgentId: original.creatorAgentId,
     source: "system",
     taskType: "reroute-decision",
@@ -630,6 +685,7 @@ export async function createPoolStarvationDecisionTask(args: {
   const created = await createTaskExtended(decision.text, {
     agentId: leadAgent.id,
     routingReason: "overflow",
+    routingSource: "engine_default",
     creatorAgentId: original.creatorAgentId,
     source: "system",
     taskType: "reroute-decision",

package/src/tests/acp-adapter.test.ts

@@ -264,7 +264,7 @@ class FakeAgent {
               },
             },
           },
-          diagnosticToken: "ghp_abcdefghijklmnopqrstuvwxyz0123456789",
+          diagnosticToken: "example-ghp_abcdefghijklmnopqrstuvwxyz0123456789",
           chunks: Array.from({ length: 20 }, () => "y".repeat(2_000)),
         },
       },
@@ -283,7 +283,7 @@ class FakeAgent {
       stopReason: "end_turn",
       usage,
       _meta: {
-        debug: "ghp_abcdefghijklmnopqrstuvwxyz0123456789",
+        debug: "example-ghp_abcdefghijklmnopqrstuvwxyz0123456789",
         authorization: "opaque-response-credential",
         note: "response metadata",
       },
@@ -475,7 +475,7 @@ new AgentSideConnection((connection) => new FakeAgent(connection), stream);
         }
         expect(persistedJson).toContain("X-Debug");
         expect(persistedJson).toContain("X-Debug-Map");
-        expect(persistedJson).not.toContain("ghp_abcdefghijklmnopqrstuvwxyz0123456789");
+        expect(persistedJson).not.toContain("example-ghp_abcdefghijklmnopqrstuvwxyz0123456789");
         expect(persistedJson).toContain("[REDACTED:github_token]");
         expect(persistedJson).toContain("… [truncated]");
         expect(persistedJson).not.toContain("x".repeat(30_001));
@@ -510,7 +510,7 @@ new AgentSideConnection((connection) => new FakeAgent(connection), stream);
           PATH: "/bin",
           HOME: "/home/test",
           ACP_TARGET: "opencode",
-          OPENAI_API_KEY: "test-key",
+          OPENAI_API_KEY: "example-test-key",
           OPENCODE_CONFIG_CONTENT: JSON.stringify({ theme: "dark" }),
         },
       }),
@@ -525,13 +525,13 @@ new AgentSideConnection((connection) => new FakeAgent(connection), stream);
             PATH: "/bin",
             HOME: "/home/test",
             ACP_TARGET: "opencode",
-            OPENAI_API_KEY: "test-key",
+            OPENAI_API_KEY: "example-test-key",
             OPENCODE_CONFIG_CONTENT: JSON.stringify({ theme: "dark" }),
           },
         }),
       ),
     ).toMatchObject({
-      OPENAI_API_KEY: "test-key",
+      OPENAI_API_KEY: "example-test-key",
       OPENCODE_CONFIG_CONTENT: JSON.stringify({ theme: "dark", model: "opencode/model" }),
     });
   });
@@ -596,8 +596,8 @@ new AgentSideConnection((connection) => new FakeAgent(connection), stream);
       ]),
     ).toEqual([{ type: "boolean", id: "flag", name: "Flag", currentValue: true }]);
 
-    const secret = "ghp_abcdefghijklmnopqrstuvwxyz1234567890";
-    const redacted = "[REDACTED:github_token]";
+    const secret = "example-ghp_abcdefghijklmnopqrstuvwxyz1234567890";
+    const redacted = "example-[REDACTED:github_token]";
     const sanitized = sanitizeAcpConfigOptions([
       {
         type: "select",
@@ -729,7 +729,7 @@ new AgentSideConnection((connection) => new FakeAgent(connection), stream);
     );
 
     // Minimal swarm API stub: tracks calls to the session token endpoints.
-    const FAKE_TOKEN = "aseph_ephemtesttoken12345678901234";
+    const FAKE_TOKEN = "example-aseph_ephemtesttoken12345678901234";
     const FAKE_TOKEN_ID = "fake-ephem-token-id";
     let mintCalled = false;
     let revokeCalled = false;
@@ -781,7 +781,7 @@ new AgentSideConnection((connection) => new FakeAgent(connection), stream);
         baseConfig({
           cwd,
           apiUrl: `http://127.0.0.1:${swarmPort}`,
-          apiKey: "real-operator-key",
+          apiKey: "example-real-operator-key",
           env: {
             PATH: process.env.PATH ?? "",
             HOME: process.env.HOME ?? "",

package/src/tests/agent-fs-live-url.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { buildAgentFsLiveUrl } from "../utils/constants";
+
+const originalHost = process.env.AGENT_FS_LIVE_URL;
+
+beforeEach(() => {
+  process.env.AGENT_FS_LIVE_URL = "https://files.example.test/";
+});
+
+afterEach(() => {
+  if (originalHost === undefined) delete process.env.AGENT_FS_LIVE_URL;
+  else process.env.AGENT_FS_LIVE_URL = originalHost;
+});
+
+describe("buildAgentFsLiveUrl path encoding", () => {
+  test.each([
+    ["plain ASCII positive control", "/reports/report-2026_v1.txt", "reports/report-2026_v1.txt"],
+    [
+      "spaces in every segment",
+      "/shared reports/final report.md",
+      "shared%20reports/final%20report.md",
+    ],
+    ["Unicode and URL syntax", "/reports/café #1?.md", "reports/caf%C3%A9%20%231%3F.md"],
+    [
+      "already encoded positive control",
+      "/reports/final%20report%2f%2520.md",
+      "reports/final%20report%2f%2520.md",
+    ],
+    [
+      "mixed raw and encoded text",
+      "/shared%20reports/final%20report 100%.md",
+      "shared%20reports/final%20report%20100%25.md",
+    ],
+    ["malformed percent escapes", "/reports/100% %2 %GG.md", "reports/100%25%20%252%20%25GG.md"],
+  ])("%s", (_label, path, expectedPath) => {
+    expect(buildAgentFsLiveUrl({ path, orgId: "org-1", driveId: "drive-1" })).toBe(
+      `https://files.example.test/file/~/org-1/drive-1/${expectedPath}`,
+    );
+  });
+});