@desplega.ai/agent-swarm 1.145.0 → 1.147.0

package/src/http/sessions.ts

@@ -2,7 +2,9 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { countSessions, getRootTaskChain, getTaskById, listRecentSessions } from "../be/db";
 import { getTaskSteeringFields } from "../be/steering";
+import { mintSessionToken, revokeSessionToken } from "../be/users";
 import { AgentTaskSchema, AgentTaskStatusSchema, SteerModeSchema } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
 
@@ -68,6 +70,57 @@ const TaskWithSteeringSchema = AgentTaskSchema.extend({
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
+/** Maximum TTL for an ephemeral session token: 7 days. */
+const MAX_SESSION_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+const mintSessionTokenRoute = route({
+  method: "post",
+  path: "/api/sessions/tokens",
+  pattern: ["api", "sessions", "tokens"],
+  summary: "Mint an ephemeral session token for an ACP provider session",
+  description:
+    "Returns a short-lived aseph_ bearer for use by the ACP adapter in place of the full " +
+    "operator key. The token expires at the requested TTL and is actively revoked when the " +
+    "session ends. Only the operator key may mint session tokens.",
+  tags: ["Sessions"],
+  body: z.object({
+    agentId: z.string().min(1),
+    taskId: z.string().min(1),
+    ttlMs: z.number().int().positive().max(MAX_SESSION_TOKEN_TTL_MS),
+  }),
+  responses: {
+    200: {
+      description: "Minted token plaintext (returned once) and its stable token ID",
+      schema: z.object({
+        tokenId: z.string(),
+        plaintext: z.string(),
+      }),
+    },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+  rbac: { ungated: "operator-only: minting is gated on the full operator key in auth middleware" },
+});
+
+const revokeSessionTokenRoute = route({
+  method: "delete",
+  path: "/api/sessions/tokens/{tokenId}",
+  pattern: ["api", "sessions", "tokens", null],
+  summary: "Revoke an ephemeral session token",
+  description: "Revokes an aseph_ bearer token by ID. No-op if already revoked.",
+  tags: ["Sessions"],
+  params: z.object({ tokenId: z.string() }),
+  responses: {
+    204: { description: "Token revoked (or was already revoked)" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+  rbac: {
+    ungated: "operator-only: revocation is gated on the full operator key in auth middleware",
+  },
+});
+
 const listSessions = route({
   method: "get",
   path: "/api/sessions",
@@ -136,6 +189,35 @@ export async function handleSessions(
   pathSegments: string[],
   queryParams: URLSearchParams,
 ): Promise<boolean> {
+  if (mintSessionTokenRoute.match(req.method, pathSegments)) {
+    // Restrict to the full operator key — aseph_ and aswt_ bearers must not be
+    // able to mint new session tokens.
+    if (getRequestAuth(req)?.kind !== "operator") {
+      jsonError(res, "Unauthorized", 401);
+      return true;
+    }
+    const parsed = await mintSessionTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const { agentId, taskId, ttlMs } = parsed.body;
+    const token = await mintSessionToken(agentId, taskId, ttlMs);
+    mintSessionTokenRoute.respond(res, 200, { tokenId: token.tokenId, plaintext: token.plaintext });
+    return true;
+  }
+
+  if (revokeSessionTokenRoute.match(req.method, pathSegments)) {
+    // Restrict revocation to the operator key as well.
+    if (getRequestAuth(req)?.kind !== "operator") {
+      jsonError(res, "Unauthorized", 401);
+      return true;
+    }
+    const parsed = await revokeSessionTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    await revokeSessionToken(parsed.params.tokenId);
+    res.writeHead(204);
+    res.end();
+    return true;
+  }
+
   if (listSessions.match(req.method, pathSegments)) {
     const parsed = await listSessions.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;

package/src/http/tasks.ts

@@ -515,7 +515,9 @@ const listPausedTasks = route({
   responses: {
     200: {
       description: "Paused task list",
-      schema: z.object({ tasks: z.array(AgentTaskSchema) }),
+      schema: z.object({
+        tasks: z.array(AgentTaskSchema.extend({ attachments: z.array(TaskAttachmentSchema) })),
+      }),
     },
   },
 });
@@ -1449,7 +1451,13 @@ export async function handleTasks(
       return true;
     }
     const pausedTasks = await getPausedTasksForAgent(myAgentId);
-    listPausedTasks.respond(res, 200, { tasks: pausedTasks });
+    const tasks = await Promise.all(
+      pausedTasks.map(async (task) => ({
+        ...task,
+        attachments: await getTaskAttachments(task.id),
+      })),
+    );
+    listPausedTasks.respond(res, 200, { tasks });
     return true;
   }
 

package/src/http/utils.ts

@@ -1,19 +1,97 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { getActiveTaskCount } from "../be/db";
 import type { SwarmSpan } from "../otel";
+import { isEnvFlagEnabled } from "../utils/env-flag";
 import { scrubSecrets } from "../utils/secret-scrubber";
 
+const DEFAULT_ALLOWED_ORIGINS = [
+  "https://*.agent-swarm.dev",
+  "https://*.agent-swarm.cloud",
+  "http://localhost:5274",
+  "http://127.0.0.1:5274",
+  "http://[::1]:5274",
+  "https://ui.swarm.localhost:1355",
+];
+
+let warnedAboutAllowAnyOrigin = false;
+
+/** Warn at boot (after config injection), or on first use of the deployment opt-out. */
+export function warnIfCorsAllowsAnyOrigin(): void {
+  if (isEnvFlagEnabled("CORS_ALLOW_ANY_ORIGIN", false) && !warnedAboutAllowAnyOrigin) {
+    warnedAboutAllowAnyOrigin = true;
+    console.warn(
+      "[CORS] CORS_ALLOW_ANY_ORIGIN=true: any request origin can receive non-credentialed responses; cookie-authenticated responses still require CORS_ALLOWED_ORIGINS. Set CORS_ALLOWED_ORIGINS and disable CORS_ALLOW_ANY_ORIGIN to restrict access.",
+    );
+  }
+}
+
+/** Re-read env on each request so Configuration reloads take effect immediately. */
+function getAllowedOrigins(): string[] {
+  const raw = process.env.CORS_ALLOWED_ORIGINS;
+  if (!raw || !raw.trim()) return DEFAULT_ALLOWED_ORIGINS;
+  return raw
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Decide whether `origin` may receive credentialed CORS headers.
+ * Unset or blank uses the built-in hosted/dev allowlist. Exact entries retain
+ * their case-sensitive string comparison. A single leading `*.` matches one or
+ * more complete hostname labels, case-insensitively, but never the apex (list
+ * it separately). Wildcard schemes and explicit ports must match exactly.
+ * Bare `*`, `https://*`, other wildcard positions, and non-origin URLs are ignored.
+ */
+export function isOriginAllowedForCredentials(origin: string): boolean {
+  const allowed = getAllowedOrigins().some((entry) => {
+    if (!entry.includes("*")) return entry === origin;
+
+    // Fixed parsers, never a regex interpolated from operator-controlled text.
+    const pattern = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/\*\.([a-zA-Z0-9.-]+)(:\d+)?$/.exec(entry);
+    const candidate = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([a-zA-Z0-9.-]+)(:\d+)?$/.exec(origin);
+    if (!pattern || !candidate) return false;
+    if (pattern[1] !== candidate[1] || pattern[3] !== candidate[3]) return false;
+
+    const suffix = pattern[2]!.toLowerCase();
+    const hostname = candidate[2]!.toLowerCase();
+    // Reject empty or malformed labels instead of accepting suffix lookalikes.
+    const validLabel = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+    if (![...suffix.split("."), ...hostname.split(".")].every((label) => validLabel.test(label))) {
+      return false;
+    }
+    return hostname.endsWith(`.${suffix}`);
+  });
+  if (!allowed) {
+    console.warn(
+      `[CORS] Denied credentialed origin ${scrubSecrets(JSON.stringify(origin.slice(0, 512)))}; add the trusted SPA origin to CORS_ALLOWED_ORIGINS (custom values replace hosted/dev defaults).`,
+    );
+  }
+  return allowed;
+}
+
 export function setCorsHeaders(req: IncomingMessage, res: ServerResponse) {
   // Echo the request Origin (rather than emitting `*`) so credentialed fetches
   // — e.g. the SPA's `credentials: 'include'` calls to `/p/:id.json` and the
   // page-session cookie endpoints — pass the browser's CORS check. A wildcard
   // would force the browser to reject any credentialed cross-origin response.
+  //
+  // Only allowlisted origins receive a credentialed CORS grant.
   const rawOrigin = req.headers.origin;
   const origin = Array.isArray(rawOrigin) ? rawOrigin[0] : rawOrigin;
+  const allowCredentials = origin ? isOriginAllowedForCredentials(origin) : false;
+  const allowAnyOrigin = isEnvFlagEnabled("CORS_ALLOW_ANY_ORIGIN", false);
+  if (allowAnyOrigin) warnIfCorsAllowsAnyOrigin();
+  if (origin && !allowCredentials && !allowAnyOrigin) {
+    res.setHeader("Vary", "Origin");
+    return;
+  }
   if (origin) {
     res.setHeader("Access-Control-Allow-Origin", origin);
     res.setHeader("Vary", "Origin");
-    res.setHeader("Access-Control-Allow-Credentials", "true");
+    // The compatibility flag never grants access to browser-supplied cookies.
+    // Bearer clients from unlisted origins must use credentials: "omit".
+    if (allowCredentials) res.setHeader("Access-Control-Allow-Credentials", "true");
     // When credentials are involved the spec disallows wildcards in
     // Allow-Headers / Allow-Methods / Expose-Headers — they must be
     // explicit. Echo whatever the preflight asked for (defensive default

package/src/prompts/session-templates.ts

@@ -74,7 +74,8 @@ Choose the path by the shape of the work:
 Store progress with \`store-progress\` at each milestone. A milestone is a result the lead could act on.
 The task is done when \`store-progress\` carries status \`completed\` and an \`output\` that names the result and every artifact link. On failure, status \`failed\` and a \`failureReason\` that names what you tried.
 When the task carries an \`outputSchema\`, \`output\` is JSON that matches it.
-When you are blocked after real effort, store the blocker with \`store-progress\` and keep working on what you can. When nothing is left to do, fail the task with a \`failureReason\` that names the blocker. The lead reads both.
+When you are blocked after real effort, store the blocker with \`store-progress\` and keep working on what you can.
+The task has four endings. When you are done: \`completed\`. When the answer needs time (a build, a deploy, a reply): \`defer-task\` with a summary of what you did, when to wake up, and what to check. It completes the task now; the wake-up task continues it. When a person must decide: \`request-human-input\`. When nothing else is possible: \`failed\` with the blocker.
 `,
   variables: [],
   category: "system",
@@ -89,9 +90,10 @@ registerTemplate({
 Your output is delegation and review. Workers implement, research, analyze, and write. Data gathering, even a quick query, goes to a worker. You answer simple factual questions yourself.
 
 \`get-swarm\` is the roster. Route by capability and load.
+Delegate with \`send-task\`. Read a child's result with \`get-task-details\`.
 A task states the goal, the repo URL when there is one, and the constraints. Workers know git, the skills, and \`store-progress\`.
 Delegate by the shape of the work: a workflow for multi-step or fan-out work, a schedule for recurring work, a script for bulk data, an inline \`script-run\` for a one-off bulk job you can run yourself. The \`workflow-iterate\`, \`scheduling\`, and \`swarm-scripts\` skills build them.
-Research or exploration: tell the worker to use \`/researching\`. A large feature: a \`/planning\` task first, then an \`/implementing\` task with \`parentTaskId\`. A small fix: direct implementation.
+Research or exploration: tell the worker to use the \`researching\` skill. A large feature: a task for the \`planning\` skill first, then a task for the \`implementing\` skill with \`parentTaskId\`. A small fix: direct implementation.
 A follow-up that continues earlier work carries \`parentTaskId\`. The worker receives the prior context.
 A task whose result depends on the workers' output: wait for the children with the \`wait-for-task\` script, then merge and complete the task yourself. A turn that ends with children still running leaves the task unfinished.
 
@@ -191,10 +193,11 @@ registerTemplate({
   defaultBody: `
 ## Outputs
 
-agent-fs is the shared drive between agents and the people you work with. A file a person will review, edit, or keep goes there. Write with the \`agent-fs\` CLI. See the \`agent-fs\` skill.
-A report or summary a person will read: publish a page with \`create_page\`. See the \`pages\` skill.
+Short answers: inline in the task output.
+agent-fs is the shared drive between agents and people. Documents (reports, digests, summaries, specs, research, drafts): Markdown files via its CLI; see \`agent-fs\` skill.
+Pages: only for polished artifacts shared with a wider audience or explicitly requested; see \`pages\` skill.
 A tool a person will use, with data and actions: build an app. See the \`apps\` skill.
-Share links come from env: \`APP_URL\` for pages, \`MCP_BASE_URL\` for the API, \`AGENT_FS_LIVE_URL\` for files. When a variable is missing, say so in your output.
+Link env: \`APP_URL\` for pages, \`MCP_BASE_URL\` for the API, \`AGENT_FS_LIVE_URL\` for files. Report missing variables.
 `,
   variables: [],
   category: "system",
@@ -206,10 +209,11 @@ registerTemplate({
   defaultBody: `
 ## Outputs
 
-agent-fs is not configured here. A file a person will review goes to a page or a task attachment.
-A report or summary a person will read: publish a page with \`create_page\`. See the \`pages\` skill.
+Short answers: inline in the task output.
+Documents: Markdown task attachments; agent-fs is not configured here.
+Pages: only for polished artifacts shared with a wider audience or explicitly requested; see \`pages\` skill.
 A tool a person will use, with data and actions: build an app. See the \`apps\` skill.
-Share links come from env: \`APP_URL\` for pages, \`MCP_BASE_URL\` for the API. When a variable is missing, say so in your output.
+Link env: \`APP_URL\` for pages, \`MCP_BASE_URL\` for the API. Report missing variables.
 `,
   variables: [],
   category: "system",

package/src/providers/acp-adapter.ts

@@ -8,9 +8,11 @@ import {
   type RequestPermissionResponse,
   type SessionConfigOption,
   type SessionNotification,
+  type Usage,
 } from "@agentclientprotocol/sdk";
 import pkg from "../../package.json";
 import type { AcpSessionConfigOption } from "../types";
+import { mintAcpSessionToken, revokeAcpSessionToken } from "../utils/acp-session-token";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import {
   detachedProcessGroup,
@@ -175,6 +177,10 @@ class ACPSession implements ProviderSession {
   private output = "";
   private completionPromise: Promise<ProviderResult>;
   private completionResolve!: (result: ProviderResult) => void;
+  /** ID of the ephemeral aseph_ token minted for this session, or null when
+   * the fallback operator key is in use (e.g. during tests or if the API is
+   * not yet upgraded). Revoked in finish(). */
+  private ephemeralTokenId: string | null = null;
 
   constructor(
     private readonly connection: ClientSideConnection,
@@ -182,8 +188,10 @@ class ACPSession implements ProviderSession {
     private readonly config: ProviderSessionConfig,
     sessionId: string,
     providerMeta?: Record<string, unknown>,
+    ephemeralTokenId?: string,
   ) {
     this.sessionId = sessionId;
+    this.ephemeralTokenId = ephemeralTokenId ?? null;
     this.completionPromise = new Promise((resolve) => {
       this.completionResolve = resolve;
     });
@@ -258,8 +266,21 @@ class ACPSession implements ProviderSession {
         sessionId: this.sessionId,
         prompt: [{ type: "text", text: this.config.prompt }],
       });
+      this.emit({
+        type: "raw_log",
+        content: serializeAcpLog({
+          type: "custom",
+          name: "acp_prompt_response",
+          data: {
+            sessionId: this.sessionId,
+            stopReason: response.stopReason,
+            usage: response.usage ?? null,
+            _meta: response._meta,
+          },
+        }),
+      });
       const isError = response.stopReason === "refusal" || response.stopReason === "cancelled";
-      const cost = this.buildCostData(isError);
+      const cost = this.buildCostData(isError, response.usage);
       result = {
         exitCode: isError ? 1 : 0,
         sessionId: this.sessionId,
@@ -302,12 +323,16 @@ class ACPSession implements ProviderSession {
     }
   }
 
-  private buildCostData(isError: boolean): CostData {
+  private buildCostData(isError: boolean, usage?: Usage | null): CostData {
     return {
       sessionId: this.sessionId,
       taskId: this.config.taskId,
       agentId: this.config.agentId,
       totalCostUsd: 0,
+      inputTokens: usage?.inputTokens,
+      outputTokens: usage?.outputTokens,
+      cacheReadTokens: usage?.cachedReadTokens ?? undefined,
+      cacheWriteTokens: usage?.cachedWriteTokens ?? undefined,
       durationMs: Date.now() - this.startedAt,
       numTurns: 1,
       model: this.config.model,
@@ -320,6 +345,11 @@ class ACPSession implements ProviderSession {
     if (this.completed) return;
     this.completed = true;
     this.completionResolve(result);
+    // Revoke the ephemeral token now that the session is done. Best-effort:
+    // the token expires on its own, so a failure here is not critical.
+    if (this.ephemeralTokenId) {
+      void revokeAcpSessionToken(this.config.apiUrl, this.config.apiKey, this.ephemeralTokenId);
+    }
   }
 }
 
@@ -355,12 +385,23 @@ export class ACPAdapter implements ProviderAdapter {
     const stream = ndJsonStream(fileSinkWritableStream(proc.stdin), proc.stdout);
     const connection = new ClientSideConnection(() => client, stream);
 
+    let ephemeralToken: { tokenId: string; plaintext: string } | null = null;
     try {
       await connection.initialize({
         protocolVersion: PROTOCOL_VERSION,
         clientInfo: { name: "agent-swarm", version: pkg.version },
         clientCapabilities: { session: { configOptions: { boolean: {} } } },
       });
+      // Mint a short-lived session-scoped bearer so the ACP target receives
+      // an aseph_ token rather than the full operator key. Throws on failure
+      // so we fail closed instead of falling back to the operator key.
+      ephemeralToken = await mintAcpSessionToken(
+        config.apiUrl,
+        config.apiKey,
+        config.agentId,
+        config.taskId,
+      );
+
       const installedServers = await fetchInstalledMcpServers(
         config.apiUrl,
         config.apiKey,
@@ -370,7 +411,7 @@ export class ACPAdapter implements ProviderAdapter {
       // The v2 draft (@agentclientprotocol/sdk/experimental/v2) adds a fourth
       // `{ type: "acp", name, serverId }` variant where the client hosts the MCP
       // server itself and the agent tunnels MCP over the existing ACP connection
-      // (mcp/connect, mcp/message, mcp/disconnect) instead of a network hop — the
+      // (mcp/connect, mcp/message, mcp/disconnect) instead of a network hop -- the
       // shape for an ACP agent with no network route to the swarm API. Gated on
       // `mcpCapabilities.acp` and UNSTABLE; not adopted here.
       const newSession = await connection.newSession({
@@ -381,7 +422,7 @@ export class ACPAdapter implements ProviderAdapter {
             name: "swarm",
             url: `${config.apiUrl.replace(/\/+$/, "")}/mcp`,
             headers: [
-              { name: "Authorization", value: `Bearer ${config.apiKey}` },
+              { name: "Authorization", value: `Bearer ${ephemeralToken.plaintext}` },
               { name: "X-Agent-ID", value: config.agentId },
               { name: "X-Source-Task-Id", value: config.taskId },
             ],
@@ -395,13 +436,26 @@ export class ACPAdapter implements ProviderAdapter {
         newSession.configOptions ?? [],
         target.configuredOptions(config),
       );
-      session = new ACPSession(connection, proc, config, newSession.sessionId, {
-        target: target.target,
-        configOptions: sanitizeAcpConfigOptions(configOptions),
-      });
+      session = new ACPSession(
+        connection,
+        proc,
+        config,
+        newSession.sessionId,
+        {
+          target: target.target,
+          configOptions: sanitizeAcpConfigOptions(configOptions),
+        },
+        ephemeralToken.tokenId,
+      );
       for (const event of preSessionEvents) session.emitFromAcp(event);
       return session;
     } catch (err) {
+      // Revoke the ephemeral token before re-throwing if ACPSession has not yet
+      // taken ownership of it (i.e. setup failed after mint but before the
+      // ACPSession constructor ran).
+      if (ephemeralToken && !session) {
+        void revokeAcpSessionToken(config.apiUrl, config.apiKey, ephemeralToken.tokenId);
+      }
       await terminateProcessGroup(proc.pid);
       throw new Error(`ACP target failed during startup: ${scrubSecrets(formatError(err))}`);
     }

package/src/providers/pi-mono-adapter.ts

@@ -191,19 +191,36 @@ export async function checkPiMonoCredentials(
   env: Record<string, string | undefined>,
   opts: CredCheckOptions = {},
 ): Promise<CredStatus> {
-  // Determine Bedrock SDK mode:
-  //   - Explicit:  BEDROCK_AUTH_MODE=sdk
+  // Determine the Bedrock mode:
+  //   - Explicit:  BEDROCK_AUTH_MODE=sdk — the AWS SDK default credential chain
+  //   - Explicit:  BEDROCK_AUTH_MODE=bearer — an explicit Bedrock API key in
+  //                AWS_BEARER_TOKEN_BEDROCK, which the AWS SDK picks up as the
+  //                bearer identity for the Bedrock clients
   //   - Fallback:  BEDROCK_AUTH_MODE absent AND MODEL_OVERRIDE starts with
   //                "amazon-bedrock/" (preserves today's prefix-inference semantics)
-  // BEDROCK_AUTH_MODE=bearer is declared/validated but the full bearer-token
-  // path is not implemented yet — it falls through to the standard auth check.
+  // Both explicit modes share the region check and the enumeration probe; they
+  // differ in what has to be present up front and in how readiness is reported.
   const bedrockAuthMode = env.BEDROCK_AUTH_MODE?.toLowerCase();
+  const isBedrockBearer = bedrockAuthMode === "bearer";
   const isBedrockSdk =
     bedrockAuthMode === "sdk" ||
     (bedrockAuthMode === undefined &&
       env.MODEL_OVERRIDE?.toLowerCase().startsWith("amazon-bedrock/"));
 
-  if (isBedrockSdk) {
+  if (isBedrockBearer && !env.AWS_BEARER_TOKEN_BEDROCK) {
+    // The token is the whole point of this mode; without it there is nothing
+    // the probe could authenticate with, and the standard API keys do not
+    // apply to Bedrock, so do not fall through to them.
+    return {
+      ready: false,
+      missing: ["AWS_BEARER_TOKEN_BEDROCK"],
+      hint: "BEDROCK_AUTH_MODE=bearer requires AWS_BEARER_TOKEN_BEDROCK (a Bedrock API key); set it, or use BEDROCK_AUTH_MODE=sdk to authenticate through the AWS credential chain.",
+      bedrockModels: [],
+      bedrockRegion: env.AWS_REGION ?? "",
+    };
+  }
+
+  if (isBedrockSdk || isBedrockBearer) {
     const region = env.AWS_REGION;
     if (!region) {
       // Do NOT fabricate a region. A guessed `us-east-1` can differ from where
@@ -231,7 +248,7 @@ export async function checkPiMonoCredentials(
       return {
         ready: true,
         missing: [],
-        satisfiedBy: "sdk-delegated",
+        satisfiedBy: isBedrockBearer ? "env" : "sdk-delegated",
         hint: `Bedrock models invocable in ${region} enumerated (${bedrockModels.length} usable; ListFoundationModels + ListInferenceProfiles).`,
         bedrockModels,
         bedrockRegion: region,

package/src/providers/pricing-sources.md

@@ -139,6 +139,17 @@ and heartbeat-classified roots are omitted, and the metrics remain separate.
   (`webSearchRequests`, per-model `costUSD`) degrade per-field without
   invalidating the entry.
 
+- **ACP usage:** optional `session/prompt` response usage supplies `inputTokens`,
+  `outputTokens`, `cachedReadTokens`, and `cachedWriteTokens`. The adapter maps
+  those counters directly; absent counters remain `undefined` only at the adapter
+  boundary. The session-cost API and DB coalesce missing input/output/cache
+  counters to zero, so persisted costs and UI displays lose unknown-vs-zero. The scrubbed
+  `acp_prompt_response` session log preserves the payload and optional `_meta`.
+  Context-window `usage_update` totals are not billing token estimates.
+  ACP reports no USD amount through `CostData`; unresolved `(acp, model)`
+  pricing identity stays `unpriced`. A target may fall back after rejecting
+  the requested model, so that requested ID alone cannot justify a rate alias.
+
 ## When a model is missing
 
 If `POST /api/session-costs` arrives with a `(provider, model)` pair that has

package/src/scheduler/scheduler.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlinkSync } from "node:fs";
-import { closeDb, createScheduledTask, initDb } from "../be/db";
-import { calculateNextRun } from "./scheduler";
+import { closeDb, createAgent, createScheduledTask, createTaskExtended, initDb } from "../be/db";
+import { calculateNextRun, createStandaloneScheduleTask } from "./scheduler";
 
 const TEST_DB_PATH = "./test-scheduler.sqlite";
 
@@ -151,3 +151,50 @@ describe("calculateNextRun", () => {
     expect(nextRun).toBe("2026-01-19T09:00:00.000Z");
   });
 });
+
+describe("createStandaloneScheduleTask", () => {
+  test("passes the schedule's parentTaskId through to the created task", async () => {
+    const agent = await createAgent({
+      name: "Deferred Wake-up Worker",
+      description: "Agent that owns the deferred task",
+      role: "worker",
+      isLead: false,
+      status: "idle",
+      maxTasks: 1,
+      capabilities: [],
+    });
+    const parent = await createTaskExtended("original work that needed time", {
+      agentId: agent.id,
+      source: "mcp",
+    });
+
+    const schedule = await createScheduledTask({
+      name: "test-deferred-parent",
+      taskTemplate: `Resume task ${parent.id}: the deploy should be green now`,
+      scheduleType: "one_time",
+      nextRunAt: new Date(Date.now() + 60_000).toISOString(),
+      targetAgentId: agent.id,
+      createdByAgentId: agent.id,
+      taskType: "deferred",
+      tags: ["deferred"],
+      parentTaskId: parent.id,
+    });
+
+    const task = await createStandaloneScheduleTask(schedule);
+    expect(task.parentTaskId).toBe(parent.id);
+    expect(task.taskType).toBe("deferred");
+    expect(task.tags).toContain("deferred");
+  });
+
+  test("a schedule without parentTaskId creates a parentless task", async () => {
+    const schedule = await createScheduledTask({
+      name: "test-no-parent",
+      taskTemplate: "Ordinary scheduled work",
+      cronExpression: "0 9 * * *",
+      timezone: "UTC",
+    });
+
+    const task = await createStandaloneScheduleTask(schedule);
+    expect(task.parentTaskId).toBeFalsy();
+  });
+});

package/src/scheduler/scheduler.ts

@@ -73,6 +73,10 @@ export async function createStandaloneScheduleTask(
     source: "schedule",
     requestedByUserId: schedule.createdBy,
     contextKey: scheduleContextKey({ scheduleId: schedule.id }),
+    // Set only by `defer-task`. An explicit parent wins over the sibling-awareness
+    // auto-wiring (see withSiblingAwareness in src/tasks/sibling-awareness.ts), so
+    // the wake-up run continues the deferred task rather than a random sibling.
+    parentTaskId: schedule.parentTaskId,
   });
 }
 

package/src/scripts-runtime/sdk-allowlist.ts

@@ -12,6 +12,7 @@ export const SDK_TOOL_NAME_MAP = {
   task_list: "get-tasks",
   task_get: "get-task-details",
   task_storeProgress: "store-progress",
+  task_defer: "defer-task",
   task_poll: "poll-task",
   task_send: "send-task",
   task_cancel: "cancel-task", // destructive

package/src/scripts-runtime/types/stdlib.d.ts

@@ -143,6 +143,14 @@ declare module "swarm-sdk" {
     task_list(args?: Record<string, unknown>): Promise<unknown>;
     task_get(args: { taskId: string }): Promise<unknown>;
     task_storeProgress(args: Record<string, unknown>): Promise<unknown>;
+    task_defer(args: {
+      taskId: string;
+      delayMs?: number;
+      runAt?: string;
+      summary: string;
+      note: string;
+      checks?: string[];
+    }): Promise<unknown>;
     task_poll(args?: Record<string, unknown>): Promise<unknown>;
     // --- kv ---
     kv_get<T = unknown>(args: {

package/src/scripts-runtime/types/swarm-sdk.d.ts

@@ -125,6 +125,14 @@ declare module "swarm-sdk" {
     task_list(args?: Record<string, unknown>): Promise<unknown>;
     task_get(args: { taskId: string }): Promise<unknown>;
     task_storeProgress(args: Record<string, unknown>): Promise<unknown>;
+    task_defer(args: {
+      taskId: string;
+      delayMs?: number;
+      runAt?: string;
+      summary: string;
+      note: string;
+      checks?: string[];
+    }): Promise<unknown>;
     task_poll(args?: Record<string, unknown>): Promise<unknown>;
     // --- kv ---
     kv_get<T = unknown>(args: {

package/src/server.ts

@@ -26,6 +26,7 @@ import { registerCreateMetricTool } from "./tools/create-metric";
 import { registerCreatePageTool } from "./tools/create-page";
 import { registerCredentialBindingsTool } from "./tools/credential-bindings";
 import { registerDbQueryTool } from "./tools/db-query";
+import { registerDeferTaskTool } from "./tools/defer-task";
 import { registerDeleteChannelTool } from "./tools/delete-channel";
 import { registerDeletePageTool } from "./tools/delete-page";
 import { registerGetMetricsTool } from "./tools/get-metrics";
@@ -421,6 +422,7 @@ export async function createServer(opts: { scriptsOnly?: boolean; fullSurface?:
   if (hasCapability("scheduling")) {
     registerListSchedulesTool(server);
     registerCreateScheduleTool(server);
+    registerDeferTaskTool(server);
     registerUpdateScheduleTool(server);
     registerPatchScheduleTool(server);
     registerDeleteScheduleTool(server);