@desplega.ai/agent-swarm 2.7.5 → 2.7.6

package/src/commands/controller.ts

@@ -15,6 +15,10 @@ async function executeCommand(
   command: ControllerCommand,
 ): Promise<unknown> {
   switch (command.op) {
+    case "release-cache":
+      if (!controller.releaseCache) throw new Error("Controller does not support cache cleanup");
+      await controller.releaseCache(command.payload);
+      return {};
     case "provision":
       return await controller.provision(command.payload);
     case "terminate":

package/src/commands/entrypoint-api-readiness.ts

@@ -0,0 +1,74 @@
+/** Worker boot step; deliberately standalone so both worker images can run it before setup. */
+export interface ApiReadinessDependencies {
+  fetch: (url: string, init: RequestInit) => Promise<Response>;
+  now: () => number;
+  sleep: (ms: number) => Promise<void>;
+  log: (message: string) => void;
+}
+
+const defaults: ApiReadinessDependencies = {
+  fetch: (url, init) => fetch(url, init),
+  now: () => performance.now(),
+  sleep: (ms) => Bun.sleep(ms),
+  log: (message) => console.log(message),
+};
+
+/** Poll the unauthenticated health endpoint before any provider reads configuration. */
+export async function waitForApiReady(
+  baseUrl: string,
+  timeoutValue = "90",
+  dependencies: Partial<ApiReadinessDependencies> = {},
+): Promise<boolean> {
+  const { fetch: probe, now, sleep, log } = { ...defaults, ...dependencies };
+  const raw = timeoutValue || "90";
+  const seconds = Number(raw);
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(seconds) || seconds <= 0) {
+    log(
+      `[entrypoint] FATAL: WORKER_API_READY_TIMEOUT_SECONDS must be a positive integer, got '${raw}'; exiting.`,
+    );
+    return false;
+  }
+
+  const url = `${baseUrl.replace(/\/$/, "")}/health`;
+  const deadline = now() + seconds * 1000;
+  log(`[entrypoint] Waiting for API readiness at ${url} (timeout ${raw}s)...`);
+  while (true) {
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      Math.min(3000, Math.max(1, deadline - now())),
+    );
+    try {
+      const response = await probe(url, { redirect: "manual", signal: controller.signal });
+      // curl -o /dev/null waited for the whole response, without retaining its body.
+      if (response.body) {
+        for await (const _chunk of response.body) {
+          // Discard health output, including error bodies, within the request timeout.
+        }
+      }
+      // Match curl -f without -L: redirects are successful and are not followed.
+      if (response.status > 0 && response.status < 400 && now() <= deadline) {
+        log(`[entrypoint] API ready at ${url}`);
+        return true;
+      }
+    } catch {
+      // The API can still be booting; retry connection, HTTP and timeout failures alike.
+    } finally {
+      clearTimeout(timer);
+    }
+    if (now() >= deadline) {
+      log(`[entrypoint] FATAL: API readiness timed out after ${raw}s waiting for ${url}; exiting.`);
+      return false;
+    }
+    await sleep(Math.min(1000, deadline - now()));
+  }
+}
+
+if (import.meta.main) {
+  process.exitCode = (await waitForApiReady(
+    Bun.argv[2] ?? "http://host.docker.internal:3013",
+    Bun.argv[3],
+  ))
+    ? 0
+    : 1;
+}

package/src/http/index.ts

@@ -877,7 +877,7 @@ httpServer
     // Delete expired MCP overflow values (10-min tick, off the spill path)
     startMcpOverflowSweep();
 
-    // Start expired-memory garbage collector (1-hour tick, immediate first run)
+    // Start expired-memory garbage collector (1-hour tick, first run 2 min after boot)
     await startMemoryGc();
 
     // Start the opt-in DB retention sweep after config hydration. Every key is

package/src/http/list-total-cache.ts

@@ -3,8 +3,11 @@
  *
  * A list total is a COUNT over the same filters as the page, and on the large
  * tables behind the sessions and task lists it costs as much as the page
- * itself. Page 1 (offset 0) always counts, so a write (a new session, a
- * triage move) shows at once where the user looks first. Later pages reuse
+ * itself. By default page 1 (offset 0) always counts, so a write (a new
+ * session, a triage move) shows at once where the user looks first. A list
+ * whose count is expensive and whose total may lag can pass
+ * `firstPageTtlMs`: page 1 then reuses a count younger than that, so
+ * dashboard tabs that poll the same list share one count. Later pages reuse
  * that count for 30 s. A cold later page (deep link, expired entry) counts
  * too, so `total` is always set.
  */
@@ -13,7 +16,7 @@ export const LIST_TOTAL_TTL_MS = 30_000;
 const MAX_ENTRIES = 500;
 
 interface Entry {
-  expiresAt: number;
+  countedAt: number;
   total: Promise<number>;
 }
 
@@ -34,19 +37,23 @@ function filterKey(value: unknown): string {
   );
 }
 
-export function createListTotalCache(ttlMs = LIST_TOTAL_TTL_MS): ListTotalCache {
+export function createListTotalCache(
+  ttlMs = LIST_TOTAL_TTL_MS,
+  firstPageTtlMs = 0,
+): ListTotalCache {
   const entries = new Map<string, Entry>();
   return {
     get(filters, offset, compute) {
       const key = filterKey(filters);
       const now = Date.now();
       const hit = entries.get(key);
-      if (hit && hit.expiresAt > now && (offset ?? 0) > 0) return hit.total;
+      const maxAge = (offset ?? 0) > 0 ? ttlMs : Math.min(ttlMs, firstPageTtlMs);
+      if (hit && hit.countedAt + maxAge > now) return hit.total;
       if (hit) entries.delete(key);
 
-      // Cache the promise, so a later page that arrives mid-count shares it.
+      // Cache the promise, so a request that arrives mid-count shares it.
       const total = compute();
-      entries.set(key, { expiresAt: now + ttlMs, total });
+      entries.set(key, { countedAt: now, total });
       total.catch(() => {
         if (entries.get(key)?.total === total) entries.delete(key);
       });

package/src/http/memory.ts

@@ -1568,17 +1568,31 @@ const MEMORY_GC_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 let memoryGcTimer: ReturnType<typeof setInterval> | null = null;
 
 const SEARCH_RETRIEVAL_TTL_DAYS = 90;
+/** Rows per purge statement. The purge yields the event loop between batches. */
+const SEARCH_RETRIEVAL_PURGE_BATCH = 2000;
 
-async function purgeStaleSearchRetrievals(): Promise<number> {
+export async function purgeStaleSearchRetrievals(
+  batchSize = SEARCH_RETRIEVAL_PURGE_BATCH,
+): Promise<number> {
   try {
     const cutoff = new Date(
       Date.now() - SEARCH_RETRIEVAL_TTL_DAYS * 24 * 60 * 60 * 1000,
     ).toISOString();
-    const result = await getDbClient().run(
-      "DELETE FROM memory_retrieval WHERE eventType = 'search' AND retrievedAt < ?",
-      [cutoff],
-    );
-    return result.changes;
+    let purged = 0;
+    for (;;) {
+      // `+eventType` keeps the planner on the retrievedAt range. Without
+      // sqlite_stat1 it prefers the eventType equality, which reads every
+      // search row to test its date, even when nothing is stale.
+      const result = await getDbClient().run(
+        `DELETE FROM memory_retrieval WHERE rowid IN (
+          SELECT rowid FROM memory_retrieval
+          WHERE +eventType = 'search' AND retrievedAt < ? LIMIT ?)`,
+        [cutoff, batchSize],
+      );
+      purged += result.changes;
+      if (result.changes < batchSize) return purged;
+      await new Promise<void>((resolve) => setImmediate(resolve));
+    }
   } catch (err) {
     console.error("[memory-gc] Search retrieval purge failed:", (err as Error).message);
     return 0;
@@ -1602,11 +1616,22 @@ async function runMemoryGcTick(label: "Initial" | "Periodic"): Promise<void> {
   }
 }
 
-export async function startMemoryGc(intervalMs = MEMORY_GC_INTERVAL_MS): Promise<void> {
+/** The first purge waits this long, so it does not compete with boot work. */
+const MEMORY_GC_INITIAL_DELAY_MS = 2 * 60 * 1000;
+let memoryGcInitialTimer: ReturnType<typeof setTimeout> | null = null;
+
+export async function startMemoryGc(
+  intervalMs = MEMORY_GC_INTERVAL_MS,
+  initialDelayMs = MEMORY_GC_INITIAL_DELAY_MS,
+): Promise<void> {
   if (memoryGcTimer) return;
 
-  // Run immediately on startup to clear any backlog
-  await runMemoryGcTick("Initial");
+  // Clear any backlog soon after startup, but off the boot path.
+  memoryGcInitialTimer = setTimeout(() => {
+    memoryGcInitialTimer = null;
+    void runMemoryGcTick("Initial");
+  }, initialDelayMs);
+  if (typeof memoryGcInitialTimer?.unref === "function") memoryGcInitialTimer.unref();
 
   memoryGcTimer = setInterval(() => {
     void runMemoryGcTick("Periodic");
@@ -1615,6 +1640,10 @@ export async function startMemoryGc(intervalMs = MEMORY_GC_INTERVAL_MS): Promise
 }
 
 export function stopMemoryGc(): void {
+  if (memoryGcInitialTimer) {
+    clearTimeout(memoryGcInitialTimer);
+    memoryGcInitialTimer = null;
+  }
   if (memoryGcTimer) {
     clearInterval(memoryGcTimer);
     memoryGcTimer = null;

package/src/http/script-runs.ts

@@ -13,10 +13,12 @@ import {
   getLatestScriptRunStepTaskByContextKey,
   getScriptRun,
   getScriptRunByIdempotencyKey,
+  getScriptRunFollowUpGuard,
   getScriptRunJournalStep,
   getTaskById,
   listScriptRunJournalSteps,
   listScriptRuns,
+  setScriptRunFollowUpGuard,
   updateScriptRun,
   updateScriptRunIfNotTerminal,
   updateScriptRunIfRunning,
@@ -24,6 +26,7 @@ import {
 } from "../be/db";
 import { explicitModelErrorForAgent } from "../be/model-validation";
 import { refuseSourceWithSecrets } from "../be/scripts/source-secrets";
+import { can } from "../rbac";
 import { lintWorkflowLabels } from "../script-workflows/label-lint";
 import { scriptRunMaxAgentTasks, scriptRunMaxSteps } from "../script-workflows/limits";
 import {
@@ -32,6 +35,12 @@ import {
   terminateScriptRunProcess,
 } from "../script-workflows/supervisor";
 import {
+  evaluateFollowUpRedelegation,
+  type FollowUpRedelegationBlock,
+  followUpThreadForSourceTask,
+} from "../tasks/follow-up-redelegation-guard";
+import {
+  type AgentTask,
   AgentTaskStatusSchema,
   RoutingReasonSchema,
   ScriptRunJournalEntrySchema,
@@ -111,6 +120,8 @@ const agentTaskBodySchema = z.object({
   parentTaskId: z.string().uuid().optional(),
   requestedByUserId: z.string().optional(),
   outputSchema: z.record(z.string(), z.unknown()).optional(),
+  /** Dispatch even when the follow-up re-delegation guard blocks it (same flag as send-task). */
+  allowRedelegation: z.boolean().optional(),
 });
 
 const scriptRunCreatedSchema = z.object({
@@ -298,10 +309,70 @@ const agentTaskRoute = route({
       description: "Agent task created or still running",
       schema: z.object({ taskId: z.string(), status: AgentTaskStatusSchema }),
     },
+    403: {
+      description:
+        "Script run belongs to another agent, or the run's agent may not create a child task under parentTaskId",
+    },
     404: { description: "Script run not found" },
+    409: { description: "Agent task failed, was cancelled, or was superseded" },
+    422: { description: "Blocked by the follow-up re-delegation guard" },
   },
 });
 
+/**
+ * Send-task's task.parent.attach decision for a `ctx.step.agentTask` step: a
+ * step inherits its parent's contextKey (its Slack or chat thread) and
+ * requester, so the run's agent needs the right to hold a child under it.
+ * Returns the 403 message, or null when allowed. A parent id with no task row
+ * passes: a step under it inherits nothing, as on send-task.
+ */
+async function stepParentRefusal(runAgentId: string, parentTaskId: string): Promise<string | null> {
+  const parentTask = await getTaskById(parentTaskId);
+  if (!parentTask) return null;
+  const runAgent = await getAgentById(runAgentId);
+  const decision = can({
+    principal: { kind: "agent", agentId: runAgentId, isLead: runAgent?.isLead ?? false },
+    verb: "task.parent.attach",
+    resource: {
+      kind: "task",
+      taskId: parentTask.id,
+      requestedByUserId: parentTask.requestedByUserId,
+      creatorAgentId: parentTask.creatorAgentId,
+      agentId: parentTask.agentId,
+    },
+    source: "http",
+  });
+  return decision.allow
+    ? null
+    : `You don't have context for parent task ${parentTaskId}. Only its assignee, its creator, or a lead can create a child task under it.`;
+}
+
+/**
+ * The launching session's task (X-Source-Task-Id), kept only when it belongs
+ * to the launching agent so a run cannot borrow another agent's session.
+ */
+async function resolveRunSourceTaskId(
+  req: IncomingMessage,
+  agentId: string,
+): Promise<string | undefined> {
+  const raw = req.headers["x-source-task-id"];
+  const sourceTaskId = Array.isArray(raw) ? raw[0] : raw;
+  if (!sourceTaskId) return undefined;
+  const task = await getTaskById(sourceTaskId);
+  return task?.agentId === agentId ? task.id : undefined;
+}
+
+/** One `ctx.step.agentTask` dispatch: the step task, or the guard rule that blocked it. */
+type StepDispatch =
+  | {
+      task: AgentTask;
+      /** True when this call inserted the step, false on a replay. */
+      created?: boolean;
+      blocked?: undefined;
+      override?: FollowUpRedelegationBlock["rule"];
+    }
+  | { task?: undefined; blocked: FollowUpRedelegationBlock; override?: undefined };
+
 async function requireAgent(res: ServerResponse, agentId: string | undefined) {
   if (!agentId) {
     jsonError(res, "X-Agent-ID required for script runs API", 400);
@@ -408,6 +479,7 @@ export async function handleScriptRuns(
     // Cap check and insert commit together: N concurrent POSTs otherwise all
     // read cap-1 active runs and all insert, exceeding the cap.
     const cap = scriptRunConcurrencyCap();
+    const sourceTaskId = await resolveRunSourceTaskId(req, agent.id);
     const creation = await getDbClient().transaction(async () => {
       if ((await countActiveScriptRuns()) >= cap) return null;
       return await createScriptRun({
@@ -418,6 +490,7 @@ export async function handleScriptRuns(
         scriptName: parsed.body.scriptName,
         idempotencyKey: parsed.body.idempotencyKey,
         requestedByUserId: parsed.body.requestedByUserId,
+        sourceTaskId,
         createdBy: parsed.body.requestedByUserId,
       });
     });
@@ -629,9 +702,29 @@ export async function handleScriptRuns(
       return true;
     }
 
+    // Only the run's own harness dispatches its steps (it sends the run's
+    // agent id). Step tasks carry that agent as creator, so another agent
+    // must not create them.
+    if (agentId !== run.agentId) {
+      jsonError(res, "Script run belongs to another agent", 403);
+      return true;
+    }
+
+    // The requested parent, checked before any lookup or insert so a refused
+    // call creates nothing.
+    if (parsed.body.parentTaskId) {
+      const refusal = await stepParentRefusal(run.agentId, parsed.body.parentTaskId);
+      if (refusal) {
+        jsonError(res, refusal, 403);
+        return true;
+      }
+    }
+
     const contextKey = `script-run:${run.id}:${parsed.body.stepKey}`;
     let task = await getLatestScriptRunStepTaskByContextKey(contextKey);
+    let dispatchedHere = false;
     if (!task) {
+      const taskDescription = parsed.body.template ?? parsed.body.task ?? parsed.body.stepKey;
       const modelError = await explicitModelErrorForAgent({
         model: parsed.body.model,
         allowCustomModel: parsed.body.allowCustomModel,
@@ -641,10 +734,47 @@ export async function handleScriptRuns(
         jsonError(res, modelError, 400);
         return true;
       }
+      const followUpThread = await followUpThreadForSourceTask(run.sourceTaskId);
+      // The replay lookup, the guard decision and the insert share one write
+      // transaction. It serializes this step against the run's other steps,
+      // other runs and send-task dispatches into the same thread.
+      let dispatched: StepDispatch;
       try {
-        task = await createTaskExtended(
-          parsed.body.template ?? parsed.body.task ?? parsed.body.stepKey,
-          {
+        dispatched = await getDbClient().transaction(async (): Promise<StepDispatch> => {
+          const replayed = await getLatestScriptRunStepTaskByContextKey(contextKey);
+          if (replayed) return { task: replayed };
+
+          // Follow-up re-delegation guard, as in send-task. A run is one
+          // dispatch: its first new step decides for the whole run, and every
+          // later step follows that decision. Later steps never compare against
+          // the run's own completed steps, a long run cannot use up the thread's
+          // loop cap, and parallel steps are dispatched all or none.
+          let override: FollowUpRedelegationBlock["rule"] | undefined;
+          if (followUpThread) {
+            const decision = await getScriptRunFollowUpGuard(run.id);
+            if (decision !== "passed") {
+              const blocked: FollowUpRedelegationBlock | null =
+                decision === null
+                  ? await evaluateFollowUpRedelegation({
+                      ...followUpThread,
+                      creatorAgentId: run.agentId,
+                      taskDescription,
+                      targetAgentId: parsed.body.agentId,
+                    })
+                  : {
+                      rule: decision,
+                      message: `Blocked by the follow-up re-delegation guard (${decision} rule): an earlier step of this script run was blocked, and a run counts as one dispatch. If it must run, pass allowRedelegation: true.`,
+                    };
+              if (blocked && !parsed.body.allowRedelegation) {
+                if (decision === null) await setScriptRunFollowUpGuard(run.id, blocked.rule);
+                return { blocked };
+              }
+              override = blocked?.rule;
+              await setScriptRunFollowUpGuard(run.id, "passed");
+            }
+          }
+
+          const created = await createTaskExtended(taskDescription, {
             agentId: parsed.body.agentId,
             routingReason:
               parsed.body.routingReason ?? (parsed.body.agentId ? "human_pinned" : undefined),
@@ -660,6 +790,20 @@ export async function handleScriptRuns(
             offeredTo: parsed.body.offerMode ? parsed.body.agentId : undefined,
             taskType: "script-run-step",
             source: "mcp",
+            // Counts the run toward the launcher's follow-up loop cap.
+            creatorAgentId: run.agentId,
+            // With no parent, the step inherits the launching session's Slack
+            // thread, as a send-task from that session does.
+            sourceTaskId: run.sourceTaskId,
+            // A guarded run's steps are its dispatches into the follow-up's
+            // thread, whatever their parent, so the guard sees them there.
+            ...(followUpThread
+              ? {
+                  slackChannelId: followUpThread.channelId,
+                  slackThreadTs: followUpThread.threadTs,
+                  slackUserId: followUpThread.userId,
+                }
+              : {}),
             dir: parsed.body.dir,
             vcsRepo: parsed.body.vcsRepo,
             model: parsed.body.model,
@@ -667,8 +811,9 @@ export async function handleScriptRuns(
             requestedByUserId: parsed.body.requestedByUserId ?? run.requestedByUserId,
             outputSchema: parsed.body.outputSchema,
             contextKey,
-          },
-        );
+          });
+          return { task: created, created: true, override };
+        });
       } catch (error) {
         if (error instanceof ExtensionAgentAssignmentError) {
           jsonError(res, error.message, 400);
@@ -676,6 +821,30 @@ export async function handleScriptRuns(
         }
         throw error;
       }
+      if (dispatched.override) {
+        console.log(
+          `[script-runs] follow-up re-delegation override: rule=${dispatched.override} runId=${run.id} creatorAgentId=${run.agentId} sourceTaskId=${run.sourceTaskId} thread=${followUpThread?.channelId}/${followUpThread?.threadTs}`,
+        );
+      }
+      if (!dispatched.task) {
+        json(res, { error: dispatched.blocked.message, rule: dispatched.blocked.rule }, 422);
+        return true;
+      }
+      task = dispatched.task;
+      dispatchedHere = dispatched.created === true;
+    }
+
+    // A replay answers from the selected step, whatever parent this call sent
+    // (or omitted), so authorize the parent the step actually holds. Every
+    // replay lookup above lands here before any output is returned. A step this
+    // call just dispatched was authorized above; refusing it now would leave
+    // the work running behind a 403.
+    if (!dispatchedHere && task.parentTaskId) {
+      const refusal = await stepParentRefusal(run.agentId, task.parentTaskId);
+      if (refusal) {
+        jsonError(res, refusal, 403);
+        return true;
+      }
     }
 
     const deadline = Date.now() + 30_000;

package/src/http/status.ts

@@ -45,6 +45,7 @@ import { getSlackConnectionState } from "../slack/connection-state";
 import { isTelemetryEnabled } from "../telemetry";
 import { type AgentCredStatus, AutomationIntegrationIdSchema, ProviderNameSchema } from "../types";
 import { isRuntimePoolsEnabled } from "../utils/runtime-pools-flag";
+import { resolveAppUrl } from "./config-values";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
@@ -116,6 +117,12 @@ export const StatusIdentitySchema = z.object({
    * cloud installs can be sliced server-side.
    */
   org_id: z.string().nullable(),
+  /**
+   * The swarm's public dashboard URL (`APP_URL`, then `DASHBOARD_URL`, with
+   * swarm_config precedence). Null when neither is set. The dashboard reads
+   * links to it in agent output as its own. Absent on older APIs.
+   */
+  dashboard_url: z.string().nullable().optional(),
 });
 export type StatusIdentity = z.infer<typeof StatusIdentitySchema>;
 
@@ -334,7 +341,7 @@ export async function rollupCredStatusForProvider(provider: string): Promise<Cre
 
 // ─── Identity ────────────────────────────────────────────────────────────────
 
-function buildIdentity(): StatusIdentity {
+function buildIdentity(dashboardUrl: string | null): StatusIdentity {
   const cloudRaw = process.env.SWARM_CLOUD;
   const hideRaw = process.env.SWARM_HIDE_CLOUD_PROMO;
   return {
@@ -345,6 +352,7 @@ function buildIdentity(): StatusIdentity {
     marketing_url: process.env.SWARM_MARKETING_URL?.trim() || null,
     hide_cloud_promo: hideRaw === "true" || hideRaw === "1",
     org_id: process.env.SWARM_ORG_ID?.trim() || null,
+    dashboard_url: dashboardUrl,
   };
 }
 
@@ -759,7 +767,7 @@ export async function buildStatusPayload(): Promise<StatusResponse> {
   const instance = await getInstanceFeedbackSignals();
   return {
     runtime_pools: { enabled: isRuntimePoolsEnabled(), supervisor: runtimeSupervisorStatus() },
-    identity: buildIdentity(),
+    identity: buildIdentity(await resolveAppUrl()),
     setup,
     activity: { ...activity, leads_ready: readyLeads },
     agent_fs: {

package/src/http/tasks.ts

@@ -84,7 +84,7 @@ import {
 import { ensure } from "../utils/business-use";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
-import { createListTotalCache } from "./list-total-cache";
+import { createListTotalCache, LIST_TOTAL_TTL_MS } from "./list-total-cache";
 import {
   agentFirstPrincipal,
   authUserId,
@@ -224,7 +224,9 @@ const SupersedeTaskResponseSchema = z.object({
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
-const taskTotals = createListTotalCache();
+// The task list total scans every visible task, and only the pager shows it,
+// so page 1 polls reuse a total younger than 15 s.
+const taskTotals = createListTotalCache(LIST_TOTAL_TTL_MS, 15_000);
 
 const listTasks = route({
   method: "get",

package/src/providers/amp-adapter.ts

@@ -45,7 +45,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1793275344-g17bf52";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1793363705-g5c9ae5";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/providers/fx-adapter.ts

@@ -21,7 +21,7 @@ import type {
  * Dockerfile.worker; bump the two together). Every ACP shape this adapter
  * relies on was measured against it.
  */
-export const FX_PINNED_VERSION = "0.0.15";
+export const FX_PINNED_VERSION = "0.0.16";
 
 /** OpenAI's Chat Completions prefix; fx appends `/chat/completions`. */
 export const FX_OPENAI_BASE_URL = "https://api.openai.com/v1";

package/src/runtime-providers/controller-protocol.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { RuntimeProviderKindSchema } from "../types";
+import { RuntimePoolCacheSchema, RuntimeProviderKindSchema } from "../types";
 
 export const CONTROLLER_PROTOCOL_VERSION = 1;
 export const CONTROLLER_COMMAND_TIMEOUT_MS = 60_000;
@@ -16,6 +16,7 @@ const traitsSchema = z.object({
   canProvision: z.boolean(),
   ephemeralDisk: z.boolean(),
   supportsPause: z.boolean(),
+  persistentCache: z.boolean().optional(),
   maxTtlSec: z.number().positive().optional(),
   maxContinuousSec: z.number().positive().optional(),
 });
@@ -31,9 +32,21 @@ const provisionSchema = z.object({
     .object({ cpu: z.number().positive().optional(), memoryMb: z.number().positive().optional() })
     .optional(),
   ttlSec: z.number().positive().optional(),
+  cache: RuntimePoolCacheSchema.extend({
+    key: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/),
+  }).optional(),
 });
 const command = { type: z.literal("cmd"), id: z.string().min(1) };
 export const ControllerCommandSchema = z.discriminatedUnion("op", [
+  z.object({
+    ...command,
+    op: z.literal("release-cache"),
+    payload: z.object({
+      key: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/),
+      poolId: z.string().min(1),
+      ownerId: z.string().min(1),
+    }),
+  }),
   z.object({ ...command, op: z.literal("provision"), payload: provisionSchema }),
   z.object({
     ...command,

package/src/runtime-providers/controller.ts

@@ -1,6 +1,7 @@
 import { scrubSecrets } from "../utils/secret-scrubber";
 import type {
   ProvisionRequest,
+  RuntimeCacheReference,
   RuntimeHandle,
   RuntimeProvider,
   RuntimeProviderTraits,
@@ -25,6 +26,7 @@ export interface ControllerCommands {
   terminate(handle: RuntimeHandle, reason: string): Promise<void>;
   status(handles: RuntimeHandle[]): Promise<Record<string, RuntimeStatus>>;
   list(ownerId: string): Promise<RuntimeHandle[]>;
+  releaseCache?(cache: RuntimeCacheReference): Promise<void>;
   renew?(handle: RuntimeHandle, ttlSec: number): Promise<{ endAt: string }>;
   pause?(handle: RuntimeHandle): Promise<void>;
   resume?(handle: RuntimeHandle): Promise<void>;
@@ -36,6 +38,7 @@ export class BuiltinController implements ControllerCommands {
   readonly renew?: ControllerCommands["renew"];
   readonly pause?: ControllerCommands["pause"];
   readonly resume?: ControllerCommands["resume"];
+  readonly releaseCache?: ControllerCommands["releaseCache"];
 
   constructor(
     readonly id: string,
@@ -47,6 +50,8 @@ export class BuiltinController implements ControllerCommands {
     this.workerApiUrl = workerApiUrl;
     if (provider.renew)
       this.renew = (handle, ttlSec) => this.call(() => provider.renew!(target, handle, ttlSec));
+    if (provider.releaseCache)
+      this.releaseCache = (cache) => this.call(() => provider.releaseCache!(target, cache));
     if (provider.pause) this.pause = (handle) => this.call(() => provider.pause!(target, handle));
     if (provider.resume)
       this.resume = (handle) => this.call(() => provider.resume!(target, handle));