@desplega.ai/agent-swarm 1.146.0 → 1.147.0

package/src/utils/acp-session-token.ts

@@ -0,0 +1,56 @@
+/**
+ * HTTP helpers used by the ACP adapter to mint and revoke ephemeral session
+ * tokens via the swarm API. This keeps the provider layer free of direct
+ * DB imports while still allowing the adapter to exchange the full operator
+ * key for a short-lived aseph_ bearer before handing credentials to the
+ * ACP target process.
+ */
+
+/** Wall-clock TTL for a session token: 24 hours. Long enough for any realistic
+ * ACP session; the token is actively revoked when the session finishes anyway. */
+export const ACP_SESSION_TOKEN_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Ask the swarm API to mint a short-lived `aseph_` bearer for the given
+ * agent + task. Throws if the request fails so callers fail closed rather
+ * than falling back to the full operator key.
+ */
+export async function mintAcpSessionToken(
+  apiUrl: string,
+  apiKey: string,
+  agentId: string,
+  taskId: string,
+): Promise<{ tokenId: string; plaintext: string }> {
+  const res = await fetch(`${apiUrl.replace(/\/+$/, "")}/api/sessions/tokens`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ agentId, taskId, ttlMs: ACP_SESSION_TOKEN_TTL_MS }),
+  });
+  if (!res.ok) {
+    throw new Error(`\x1b[33m[acp]\x1b[0m Session token mint failed (${res.status})`);
+  }
+  const data = (await res.json()) as { tokenId: string; plaintext: string };
+  return { tokenId: data.tokenId, plaintext: data.plaintext };
+}
+
+/**
+ * Ask the swarm API to revoke a previously-minted `aseph_` token. Best-effort:
+ * errors are logged but never propagated to the caller.
+ */
+export async function revokeAcpSessionToken(
+  apiUrl: string,
+  apiKey: string,
+  tokenId: string,
+): Promise<void> {
+  try {
+    await fetch(`${apiUrl.replace(/\/+$/, "")}/api/sessions/tokens/${tokenId}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+  } catch {
+    // best-effort — token will expire on its own
+  }
+}

package/src/utils/file-lock.ts

@@ -0,0 +1,111 @@
+/**
+ * Advisory cross-process lock held by the kernel: flock(2) on a lock file, via
+ * `bun:ffi` (Bun and Node expose no flock).
+ *
+ * Makes a multi-file state transition exclusive across processes of the same
+ * user. First use: the Claude hook rewrites `~/.claude/CLAUDE.md` together with
+ * its lineage record, and the hook and the runner read that pair — a reader
+ * landing between the two writes can misjudge the file (see
+ * `src/commands/claude-md-session.ts`).
+ *
+ * Why the kernel and not a lock file with a staleness threshold: a threshold
+ * cannot tell a slow holder (a stalled filesystem, a suspended process) from a
+ * dead one, so it eventually lets a second process into a transition that is
+ * still running. flock is released only when the holder closes its descriptor or
+ * dies, so it can never be taken from a live holder and needs no breaking.
+ *
+ * The lock file is never deleted: unlinking a locked path would let a newcomer
+ * create and lock a different inode while the old one is still held.
+ */
+
+import { dlopen, FFIType } from "bun:ffi";
+// A file handle whose descriptor stays open while the lock is held has no Bun
+// equivalent; neither does directory creation.
+import { mkdir, open } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+
+export type Flock = (fd: number, operation: number) => number;
+
+const LIBC_CANDIDATES =
+  process.platform === "darwin"
+    ? ["libc.dylib", "/usr/lib/libSystem.B.dylib"]
+    : ["libc.so.6", "libc.so", "libc.musl-x86_64.so.1", "libc.musl-aarch64.so.1"];
+
+let flockImpl: Flock | null | undefined;
+
+function loadFlock(): Flock | null {
+  if (flockImpl !== undefined) return flockImpl;
+  flockImpl = null;
+  for (const name of LIBC_CANDIDATES) {
+    try {
+      const { symbols } = dlopen(name, {
+        flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+      });
+      flockImpl = (fd, operation) => symbols.flock(fd, operation);
+      break;
+    } catch {
+      // try the next libc name
+    }
+  }
+  return flockImpl;
+}
+
+const DEFAULTS = { waitMs: 15_000, pollMs: 25 };
+
+export interface FileLockOptions {
+  /** How long to wait for a held lock before giving up (default 15 s). */
+  waitMs?: number;
+  /** Poll interval while waiting (default 25 ms). */
+  pollMs?: number;
+}
+
+export type FileLockResult<T> =
+  | { acquired: true; value: T }
+  /**
+   * `busy`: another live process holds it (or flock keeps refusing).
+   * `error`: the lock file could not be created or opened.
+   * `unsupported`: no flock on this platform.
+   */
+  | { acquired: false; reason: "busy" | "error" | "unsupported"; error?: unknown };
+
+/** Test seam: replace the flock binding (`null` = unsupported platform, `undefined` = real). */
+export function setFlockForTests(impl: Flock | null | undefined): void {
+  flockImpl = impl;
+}
+
+/**
+ * Run `fn` while holding the lock. Never runs `fn` without it: callers decide
+ * what a `busy`, `error` or `unsupported` result means for them. Errors thrown
+ * by `fn` propagate (after the lock is released).
+ */
+export async function withFileLock<T>(
+  lockPath: string,
+  fn: () => Promise<T>,
+  options: FileLockOptions = {},
+): Promise<FileLockResult<T>> {
+  const flock = loadFlock();
+  if (!flock) return { acquired: false, reason: "unsupported" };
+  const waitMs = options.waitMs ?? DEFAULTS.waitMs;
+  const pollMs = options.pollMs ?? DEFAULTS.pollMs;
+
+  let handle: Awaited<ReturnType<typeof open>>;
+  try {
+    await mkdir(dirname(lockPath), { recursive: true });
+    handle = await open(lockPath, "a");
+  } catch (error) {
+    return { acquired: false, reason: "error", error };
+  }
+  try {
+    const deadline = Date.now() + waitMs;
+    while (flock(handle.fd, LOCK_EX | LOCK_NB) !== 0) {
+      if (Date.now() >= deadline) return { acquired: false, reason: "busy" };
+      await Bun.sleep(pollMs);
+    }
+    return { acquired: true, value: await fn() };
+  } finally {
+    await handle.close(); // closing the descriptor releases the lock
+  }
+}

package/src/utils/heartbeat-expiry.ts

@@ -0,0 +1,78 @@
+import { scrubSecrets } from "./secret-scrubber";
+
+const EXPIRY = /delete\s+(on\s+)?\d{2}-\d{2}/i;
+
+function trackedLines(markdown: string): string[] {
+  const marker = "## Tracked Items";
+  const start = markdown.lastIndexOf(marker);
+  if (start < 0) return [];
+  const lineEnd = markdown.indexOf("\n", start);
+  if (lineEnd < 0) return [];
+  // Stop at the next peer/parent section; subheadings may group tracked items.
+  const section = markdown.slice(lineEnd + 1).split(/^#{1,2}\s/m)[0] ?? "";
+  return section
+    .split(/\r?\n/)
+    .map((line) => line.trim().replace(/^(?:[-*+]\s+|\d+[.)]\s+)(?:\[[ xX]\]\s*)?/, ""))
+    .filter((line) => line && !line.startsWith("#") && !/^[-*_]{3,}$/.test(line));
+}
+
+function title(line: string): string | undefined {
+  return /^\*\*([^*]+)\*\*/.exec(line)?.[1];
+}
+
+// Deleting text anywhere in a legacy line is cleanup, not a new item.
+function isShortening(old: string, next: string): boolean {
+  let cursor = 0;
+  for (const character of next) {
+    const index = old.indexOf(character, cursor);
+    if (index < 0) return false;
+    cursor = index + character.length;
+  }
+  return true;
+}
+
+export class HeartbeatExpiryError extends Error {
+  constructor(line: string) {
+    super(
+      scrubSecrets(
+        `Update rejected for heartbeatMd: new tracked item requires DELETE <MM-DD> (or DELETE on <MM-DD>): ${line}`,
+      ),
+    );
+    this.name = "HeartbeatExpiryError";
+  }
+}
+
+/** Grandfather existing lines, but never let one old item cover two new ones. */
+export function validateHeartbeatExpiry(currentValue: string, nextValue: string): void {
+  const previous = trackedLines(currentValue);
+  const incoming = trackedLines(nextValue);
+  // Consume exact matches first so an unchanged item cannot sponsor a new item.
+  const changed = incoming.filter((line) => {
+    const index = previous.indexOf(line);
+    if (index < 0) return true;
+    previous.splice(index, 1);
+    return false;
+  });
+  // Dated/pinned replacements also consume their old item before undated edits.
+  // Otherwise dating one old item could accidentally authorize an undated copy.
+  for (const line of changed) {
+    if (!line.startsWith("📌") && !EXPIRY.test(line)) continue;
+    const itemTitle = title(line.replace(/^📌\s*/, ""));
+    const index = previous.findIndex(
+      (old) => line.includes(old) || (itemTitle !== undefined && itemTitle === title(old)),
+    );
+    if (index >= 0) previous.splice(index, 1);
+  }
+  for (const line of changed) {
+    if (line.startsWith("📌") || EXPIRY.test(line)) continue;
+    const itemTitle = title(line);
+    const index = previous.findIndex(
+      (old) =>
+        !old.startsWith("📌") &&
+        !EXPIRY.test(old) &&
+        (isShortening(old, line) || (itemTitle !== undefined && itemTitle === title(old))),
+    );
+    if (index < 0) throw new HeartbeatExpiryError(line);
+    previous.splice(index, 1);
+  }
+}

package/src/utils/request-auth-context.ts

@@ -5,6 +5,8 @@ import type { User } from "../types";
 export type HttpRequestAuth = (
   | { kind: "operator"; fingerprint: string }
   | { kind: "user"; userId: string; user: User }
+  /** Ephemeral session token minted by the ACP adapter per session (aseph_ prefix). */
+  | { kind: "agent"; agentId: string; taskId: string }
 ) & {
   /** Verified page context for agent-scoped operations. This does not identify the viewer. */
   page?: { id: string; executionAgentId: string };

package/src/utils/task-attachment-links.ts

@@ -1,6 +1,28 @@
 import type { TaskAttachment } from "../types";
 import { buildAgentFsLiveUrl, getAppUrl } from "./constants";
 
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * A ready-to-run command that downloads a task attachment's bytes from inside a
+ * worker container through the provider-agnostic raw route — MCP_BASE_URL, the
+ * API key and AGENT_ID are already in every worker's env. Each attachment gets
+ * its own directory, so two attachments with the same name (every pasted
+ * screenshot is "image.png") never overwrite each other; the path is quoted
+ * because attachment names come from users.
+ */
+export function taskAttachmentFetchCommand(
+  taskId: string,
+  attachmentId: string,
+  name: string,
+): string {
+  const url = `$MCP_BASE_URL/api/fs/tasks/${taskId}/files/${attachmentId}/raw`;
+  const outPath = shellQuote(`/tmp/attachments/${attachmentId}/${name.replace(/\//g, "_")}`);
+  return `curl -s -H "Authorization: Bearer \${AGENT_SWARM_API_KEY:-$API_KEY}" -H "X-Agent-ID: $AGENT_ID" "${url}" --create-dirs -o ${outPath}`;
+}
+
 export function taskAttachmentDisplayUrl(attachment: TaskAttachment): string {
   if (attachment.kind === "url") return attachment.url ?? "";
   if (attachment.kind === "page") {

package/templates/skills/code-quality/content.md

@@ -38,11 +38,14 @@ The Repository Guidelines carry `allowMerge` and `mergeChecks`.
 
 ## Review a PR
 
-1. CI status first. Failing CI is a REQUEST_CHANGES. Name the failing checks in the review.
-2. Tests second. A code change without new or updated tests is a REQUEST_CHANGES. Name the tests you expect. Exceptions: documentation-only, configuration-only, and dependency-bump PRs.
-3. Apply the "Review Guidance" entries from the Repository Guidelines.
-4. Read the diff for security (injection, secrets in code), logic (null handling, off-by-one, edge cases), performance (N+1, leaks), and code shape (naming, duplication, error handling). Run the test suite and the type check locally when you can.
-5. Post the review with the verdict first. One finding per comment, with file and line, and what to change.
+1. CI status first, including the fork checks below before treating CI as evidence. Failing CI is a REQUEST_CHANGES. Name the failing checks in the review.
+2. Detect a GitHub fork PR with `gh pr view <number> --json isCrossRepository --jq .isCrossRepository`.
+3. For a GitHub fork PR, inspect held runs with `SHA=$(gh pr view <number> --json headRefOid --jq .headRefOid); gh api --paginate "repos/<owner>/<repo>/actions/runs?head_sha=$SHA" --jq '.workflow_runs[] | "\(.conclusion // .status)|\(.name)"'`; `gh pr checks` and `statusCheckRollup` can omit them.
+4. Treat any `action_required` run or no substantive run executed on that SHA as a CI blocker. Keep run handling read-only: REQUEST_CHANGES naming the held or unexecuted run, and report the blocker so an explicitly authorized maintainer or the application-controlled GitHub integration can approve the run after validating the workflow and its trust boundary. Do not APPROVE on omitted runs.
+5. Tests second. A code change without new or updated tests is a REQUEST_CHANGES. Name the tests you expect. Exceptions: documentation-only, configuration-only, and dependency-bump PRs.
+6. Apply the "Review Guidance" entries from the Repository Guidelines.
+7. Read the diff for security (injection, secrets in code), logic (null handling, off-by-one, edge cases), performance (N+1, leaks), and code shape (naming, duplication, error handling). Run the test suite and the type check locally when you can.
+8. Post the review with the verdict first. One finding per comment, with file and line, and what to change.
 
 ## GitHub review-reply provenance
 

package/templates/skills/download-task-attachment/content.md

@@ -12,11 +12,12 @@ discovery.
 curl "$MCP_BASE_URL/api/fs/tasks/$AGENT_SWARM_TASK_ID/files/<attachmentId>/raw" \
   -H "X-Agent-ID: $AGENT_ID" \
   -H "Authorization: Bearer ${AGENT_SWARM_API_KEY:-$API_KEY}" \
-  -o /tmp/<name>
+  --create-dirs -o "/tmp/attachments/<attachmentId>/<name>"
 ```
 
 - `$MCP_BASE_URL`, `$AGENT_ID`, `$AGENT_SWARM_TASK_ID` (or `$AGENT_SWARM_AGENT_ID`/`TASK_FILE`-derived taskId), and `$AGENT_SWARM_API_KEY`/`$API_KEY` are already present in every worker container's env — no new plumbing needed.
 - `<attachmentId>` and `<name>`/`mimeType` come from the task's attachment list (see below).
+- One directory per attachment: two attachments can share a name (every pasted screenshot is `image.png`), and `/tmp/<name>` would let one overwrite the other.
 - The route resolves the active file-storage provider (`local-fs` in dev, `agent-fs` in prod) server-side and streams the raw bytes back with the correct `Content-Type` — you get one call no matter which provider is behind it.
 
 ## Finding the attachment ID

package/{plugin/pi-skills → templates/skills}/review-offered-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-offered-task
-description: Review a task that has been offered to you and decide whether to accept or reject it
+description: "Turn prompt for an offered swarm task: read the offer, accept with task-action and start work-on-task, or reject with a reason."
 ---
 
 # Review Offered Task
@@ -17,7 +17,7 @@ You have been offered a task. Your job is to review it and decide whether to acc
    - Is the task description clear enough to proceed?
 
 3. **Make a decision**:
-   - **Accept**: If you can complete this task, call `task-action` with `action: "accept"` and `taskId: "<taskId>"`. Then immediately use `/skill:work-on-task <taskId>` to start working on it.
+   - **Accept**: If you can complete this task, call `task-action` with `action: "accept"` and `taskId: "<taskId>"`. Then immediately use the `work-on-task` skill with the taskId to start working on it.
    - **Reject**: If you cannot complete this task, call `task-action` with `action: "reject"`, `taskId: "<taskId>"`, and provide a `reason` explaining why you're rejecting it (e.g., "Task requires Python expertise which I don't have", "Task description is too vague").
 
 ## Example Accept Flow
@@ -26,7 +26,7 @@ You have been offered a task. Your job is to review it and decide whether to acc
 1. get-task-details taskId="abc-123"
 2. [Review the task details]
 3. task-action action="accept" taskId="abc-123"
-4. /skill:work-on-task abc-123
+4. /work-on-task abc-123
 ```
 
 ## Example Reject Flow
@@ -35,11 +35,11 @@ You have been offered a task. Your job is to review it and decide whether to acc
 1. get-task-details taskId="abc-123"
 2. [Review the task details]
 3. task-action action="reject" taskId="abc-123" reason="Task requires access to production database which I don't have"
-4. Reply "DONE" to end the session
+4. Stop
 ```
 
 ## Important Notes
 
 - Always provide a clear reason when rejecting a task - this helps the lead agent reassign it appropriately
-- If you accept, you must immediately start working on the task using `/skill:work-on-task`
+- If you accept, you must immediately start working on the task using the `work-on-task` skill
 - If you reject, the task returns to the unassigned pool for reassignment

package/templates/skills/review-offered-task/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "review-offered-task",
+  "displayName": "Review Offered Task",
+  "slug": "review-offered-task",
+  "title": "Review Offered Task",
+  "description": "Turn prompt for an offered swarm task: read the offer, accept with task-action and start work-on-task, or reject with a reason.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": true,
+  "tags": ["tasks", "turn-prompt", "worker"]
+}

package/{plugin/commands/review-offered-task.md → templates/skills/review-offered-task/content.md}

@@ -1,8 +1,3 @@
----
-description: Review a task that has been offered to you and decide whether to accept or reject it
-argument-hint: [taskId]
----
-
 # Review Offered Task
 
 You have been offered a task. Your job is to review it and decide whether to accept or reject it based on your capabilities and current workload.
@@ -17,7 +12,7 @@ You have been offered a task. Your job is to review it and decide whether to acc
    - Is the task description clear enough to proceed?
 
 3. **Make a decision**:
-   - **Accept**: If you can complete this task, call `task-action` with `action: "accept"` and `taskId: "<taskId>"`. Then immediately use `/work-on-task <taskId>` to start working on it.
+   - **Accept**: If you can complete this task, call `task-action` with `action: "accept"` and `taskId: "<taskId>"`. Then immediately use the `work-on-task` skill with the taskId to start working on it.
    - **Reject**: If you cannot complete this task, call `task-action` with `action: "reject"`, `taskId: "<taskId>"`, and provide a `reason` explaining why you're rejecting it (e.g., "Task requires Python expertise which I don't have", "Task description is too vague").
 
 ## Example Accept Flow
@@ -35,11 +30,11 @@ You have been offered a task. Your job is to review it and decide whether to acc
 1. get-task-details taskId="abc-123"
 2. [Review the task details]
 3. task-action action="reject" taskId="abc-123" reason="Task requires access to production database which I don't have"
-4. Reply "DONE" to end the session
+4. Stop
 ```
 
 ## Important Notes
 
 - Always provide a clear reason when rejecting a task - this helps the lead agent reassign it appropriately
-- If you accept, you must immediately start working on the task using `/work-on-task`
+- If you accept, you must immediately start working on the task using the `work-on-task` skill
 - If you reject, the task returns to the unassigned pool for reassignment

package/templates/skills/scheduling/content.md

@@ -41,6 +41,10 @@ The template is the whole task the agent receives. It must state:
 
 Tasks created by a schedule are automatic tasks. Their completed output is not stored as memory unless the agent calls `store-progress` with `persistMemory: true`.
 
+## Check back later
+
+A task whose answer needs time (a build, a deploy, a reply) calls `defer-task` with `delayMs` or `runAt`, a `summary` of what you did so far, and a `note` that says what is pending. The tool completes the task and creates the one-off schedule for you. The task reaches its final state (`completed`) on this call, and the `summary` becomes its output. The wake-up task carries the deferred task as its parent, so you receive that task's context. Add `checks` to list what to verify on wake-up. Do not hand-roll this with `create-schedule`.
+
 ## Secrets
 
 A `taskTemplate` and `scriptArgs` are stored as plain text and replayed on every run. They must not contain a token, password, or key. Call the external API from a script through a registered connection or a credential binding instead. See the `swarm-scripts` skill, section Secrets.

package/templates/skills/slack-interaction/content.md

@@ -30,12 +30,12 @@ The task carries `slackChannelId` and `slackThreadTs` in its metadata. A follow-
 | `slack-read` | read a thread by `taskId` or `inboxMessageId`, or a channel by `channelId` (lead) |
 | `slack-list-channels` | channels the bot is a member of |
 | `slack-upload-file` | upload a file to a thread or channel, up to 1 GB |
-| `slack-download-file` | download a Slack file by ID or URL |
+| `slack-download-file` | attach a Slack file (by ID or URL) to your task; run the `fetchCommand` it returns to get the bytes |
 | `slack-update` | edit your own message |
 | `slack-delete` | delete your own message (lead) |
 | `slack-create-channel`, `slack-invite-to-channel`, `slack-archive-channel` | channel lifecycle (lead) |
 
-Files attached to your task already come with download commands in the task message. Use those before `slack-download-file`.
+Files attached to your task already come with download commands in the task message. Use those before `slack-download-file`. `slack-read` on your task also attaches the files in the thread and gives each one a `fetchCommand`. Don't look for Slack files under `/app/shared` or `/workspace/shared/downloads`: those paths are the API server's disk.
 
 ## Unknown user
 

package/templates/skills/work-on-task/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: work-on-task
+description: "Turn prompt for an assigned swarm task: find the task, gather context when the message lacks it, use the skill the task names, finish with one of the four endings."
+---
+
+# Working on a task
+
+The taskId follows the command. Without one, call `get-tasks` with `mineOnly: true` and take your `pending` or `in_progress` task. If there is none, say so and stop.
+
+This message carries the task text, its attachments, its output format, and memories from past sessions. If it does not (you invoked this command yourself, or the context was compacted), run the `task-context-gathering` script with the taskId.
+
+When the task names a skill (`researching`, `planning`, `implementing`), use it. Otherwise work directly.
+
+Finish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.
+
+If the user interrupts, follow their instructions. To resume, call `/work-on-task <taskId>` again.

package/templates/skills/work-on-task/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "work-on-task",
+  "displayName": "Work On Task",
+  "slug": "work-on-task",
+  "title": "Work On Task",
+  "description": "Turn prompt for an assigned swarm task: find the task, gather context when the message lacks it, use the skill the task names, finish with one of the four endings.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": true,
+  "tags": ["tasks", "turn-prompt", "worker"]
+}

package/templates/skills/work-on-task/content.md

@@ -0,0 +1,11 @@
+# Working on a task
+
+The taskId follows the command. Without one, call `get-tasks` with `mineOnly: true` and take your `pending` or `in_progress` task. If there is none, say so and stop.
+
+This message carries the task text, its attachments, its output format, and memories from past sessions. If it does not (you invoked this command yourself, or the context was compacted), run the `task-context-gathering` script with the taskId.
+
+When the task names a skill (`researching`, `planning`, `implementing`), use it. Otherwise work directly.
+
+Finish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.
+
+If the user interrupts, follow their instructions. To resume, call `/work-on-task <taskId>` again.