@desplega.ai/agent-swarm 2.6.0 → 2.7.1

package/src/http/users.ts

@@ -20,6 +20,8 @@
  *   DELETE /api/users/:id/mcp-tokens/:tokenId
  *   POST   /api/users/:id/connector-codes
  *   POST   /api/connector/exchange                   (public: the code is the credential)
+ *   POST   /api/invites
+ *   POST   /api/invites/exchange                     (public: the code is the credential)
  *   POST   /api/users/:id/merge
  *   GET    /api/users/:id/events
  *   POST   /api/users/:id/identities
@@ -31,7 +33,10 @@ import { z } from "zod";
 import {
   createConnectorCode,
   DEFAULT_CONNECTOR_CODE_LABEL,
+  DEFAULT_INVITE_CODE_LABEL,
+  deleteUnusedInviteCodes,
   exchangeConnectorCode,
+  INVITE_CODE_TTL_MS,
 } from "../be/connector-codes";
 import {
   createUser,
@@ -45,8 +50,15 @@ import {
   updateUser,
   upsertBudget,
 } from "../be/db";
-import { assertNotLastAdmin, LastAdminError } from "../be/rbac-roles";
 import {
+  assertNotLastAdmin,
+  getUserGrant,
+  LastAdminError,
+  listUserRoles,
+  setUserRoles,
+} from "../be/rbac-roles";
+import {
+  findUserByEmail,
   getUserIdentities,
   type IdentityEvent,
   linkIdentity,
@@ -57,12 +69,16 @@ import {
   revokeToken,
   unlinkIdentity,
 } from "../be/users";
+import { isRbacEnabled } from "../rbac";
 import { UserCommsPrefsSchema, UserSchema } from "../types";
+import { DEFAULT_APP_URL } from "../utils/constants";
+import { assertUrlSafe } from "../utils/egress-guard";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { resolveAppUrl, resolveMcpBaseUrl } from "./config-values";
 import { clientIp, createIpRateLimiter } from "./ip-rate-limit";
 import { getOperatorActor } from "./operator-actor";
 import { route } from "./route-def";
+import { ensureRoleManager } from "./user-roles";
 import { jsonError } from "./utils";
 
 // ─── Response composition ────────────────────────────────────────────────────
@@ -172,6 +188,15 @@ const whoamiRoute = route({
         // `components.schemas.User` to `object | null` for every consumer;
         // the union keeps nullability local to this response field.
         user: z.union([UserSchema, z.null()]),
+        // Optional so older clients and older servers stay compatible. The
+        // dashboard hides what the caller cannot do; the server still gates.
+        grants: z
+          .object({
+            grantsAll: z.boolean(),
+            verbs: z.array(z.string()),
+            roles: z.array(z.string()),
+          })
+          .optional(),
       }),
     },
     401: { description: "Unauthorized" },
@@ -448,6 +473,80 @@ const exchangeConnectorCodeRoute = route({
   },
 });
 
+const INVITE_ROLES = ["requester", "viewer", "admin"] as const;
+
+const createInviteRoute = route({
+  method: "post",
+  path: "/api/invites",
+  pattern: ["api", "invites"],
+  summary: "Invite a teammate with a one-time API link",
+  description:
+    "Creates an invited user with the given role (requester by default) and returns a 7-day single-use API link. The API redirects to the current APP_URL dashboard with the code in the URL fragment. The browser exchanges the code at POST /api/invites/exchange for a personal MCP token. Re-inviting an invited user replaces the role and link. Active or suspended users return 409 user_exists. No email is sent.",
+  tags: ["Users"],
+  body: z.object({
+    email: z.email(),
+    name: z.string().trim().min(1).max(200).optional(),
+    role: z.enum(INVITE_ROLES).default("requester"),
+  }),
+  responses: {
+    201: {
+      description: "The invited user, API link, dashboard URL, expiry and API reachability",
+      schema: z.object({
+        user: ComposedUserSchema.nullable(),
+        inviteUrl: z.string(),
+        appUrl: z.string(),
+        expiresAt: z.string(),
+        apiReachable: z.enum(["public", "local"]),
+      }),
+    },
+    401: { description: "Unauthorized" },
+    403: { description: "Not allowed to manage roles" },
+    409: { description: "The email belongs to an active or suspended user" },
+  },
+  auth: { apiKey: true },
+  rbac: { permission: "user.role.manage" },
+});
+
+const openInviteRoute = route({
+  method: "get",
+  path: "/invite/{code}",
+  pattern: ["invite", null],
+  summary: "Open an invite in the configured dashboard",
+  description:
+    "Redirects to the current APP_URL dashboard with the code in the URL fragment. Does not validate or consume the invite.",
+  tags: ["Users"],
+  params: z.object({ code: z.string() }),
+  responses: {
+    302: { description: "Redirect to the dashboard", unstructured: "Dashboard redirect" },
+    404: { description: "Malformed code (code_invalid)" },
+  },
+  auth: { apiKey: false },
+});
+
+const exchangeInviteCodeRoute = route({
+  method: "post",
+  path: "/api/invites/exchange",
+  pattern: ["api", "invites", "exchange"],
+  summary: "Exchange an invite code for the invited user's MCP token",
+  description:
+    "Unauthenticated: the single-use invite code is the credential. Rate limited per IP. Activates the invited user. Unknown, expired, used and connector codes, and codes for users who are no longer invited, all return 404 code_invalid.",
+  tags: ["Users"],
+  body: z.object({ code: z.string().min(1).max(256) }),
+  // Public route: cap the body before it is buffered and parsed.
+  maxBodyBytes: 1024,
+  responses: {
+    200: {
+      description: "Minted MCP token for the invited user",
+      schema: z.object({ token: z.string(), userId: z.string() }),
+    },
+    404: { description: "Code unknown, malformed, expired, already used or not an invite" },
+    413: { description: "Request body too large" },
+    429: { description: "Rate limited" },
+  },
+  auth: { apiKey: false },
+  rbac: { ungated: "the one-time invite code is the credential" },
+});
+
 const connectorDiscoveryRoute = route({
   method: "get",
   path: "/api/connector/discovery",
@@ -681,6 +780,35 @@ export function _resetConnectorExchangeRateLimitForTests(): void {
   connectorExchangeRateLimiter.reset();
 }
 
+/** 10 invite exchanges per minute per client IP. */
+const inviteExchangeRateLimiter = createIpRateLimiter({
+  capacity: 10,
+  refillPerMs: 10 / 60_000,
+});
+
+export function _resetInviteExchangeRateLimitForTests(): void {
+  inviteExchangeRateLimiter.reset();
+}
+
+/**
+ * `local` when teammates' browsers likely cannot reach the API: a loopback or
+ * private IP host, a single-label name (a compose service such as
+ * `swarm-api`), or a `.local` / `.internal` / `.lan` name.
+ */
+function apiReachability(apiUrl: string): "public" | "local" {
+  let host: string;
+  try {
+    host = assertUrlSafe(apiUrl, { allowInsecure: true }).hostname.toLowerCase();
+  } catch {
+    return "local";
+  }
+  if (!host.includes(".") && !host.includes(":")) return "local";
+  if (/\.(local|internal|lan|home\.arpa)\.?$/.test(host)) return "local";
+  return "public";
+}
+
+class InviteUserExistsError extends Error {}
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleUsers(
@@ -695,9 +823,26 @@ export async function handleUsers(
     if (!parsed) return true;
     const auth = getRequestAuth(req);
     if (auth?.kind === "user") {
-      whoamiRoute.respond(res, 200, { kind: "user", user: auth.user });
+      const [grant, roles] = await Promise.all([
+        getUserGrant(auth.user.id),
+        listUserRoles(auth.user.id),
+      ]);
+      const grantsAll = !isRbacEnabled() || grant.grantsAll;
+      whoamiRoute.respond(res, 200, {
+        kind: "user",
+        user: auth.user,
+        grants: {
+          grantsAll,
+          verbs: grantsAll ? [] : [...grant.verbs].sort(),
+          roles: roles.map((role) => role.name),
+        },
+      });
     } else {
-      whoamiRoute.respond(res, 200, { kind: "operator", user: null });
+      whoamiRoute.respond(res, 200, {
+        kind: "operator",
+        user: null,
+        grants: { grantsAll: true, verbs: [], roles: [] },
+      });
     }
     return true;
   }
@@ -934,6 +1079,130 @@ export async function handleUsers(
     return true;
   }
 
+  // ─── POST /api/invites ─────────────────────────────────────────────────────
+  if (createInviteRoute.match(req.method, pathSegments)) {
+    const parsed = await createInviteRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    // Same gate as PUT /api/users/{id}/roles: an invite assigns a role, so a
+    // custom role holding user.role.manage must not hand out admin.
+    if (!(await ensureRoleManager(req, res))) return true;
+    const actor = getOperatorActor(req, res);
+    if (!actor) return true;
+    const { email, name, role } = parsed.body;
+    const actorUserId = actor.kind === "user" ? actor.id : null;
+
+    let invited: { userId: string; code: string; expiresAt: string };
+    try {
+      invited = await getDbClient().transaction(async () => {
+        const existing = await findUserByEmail(email);
+        if (existing && existing.status !== "invited") throw new InviteUserExistsError();
+        let userId: string;
+        if (existing) {
+          userId = existing.id;
+          await deleteUnusedInviteCodes(userId);
+        } else {
+          const user = await createUser({
+            name: name ?? (email.split("@")[0] || email),
+            email,
+            status: "invited",
+          });
+          userId = user.id;
+          await recordIdentityEvent(userId, "identity_added", actor, null, {
+            email,
+            source: "invite",
+          });
+        }
+        const { before, after } = await setUserRoles(userId, [role], actorUserId);
+        if (before.join(",") !== after.join(",")) {
+          await recordIdentityEvent(
+            userId,
+            "profile_changed",
+            actor,
+            { rbacRoles: before },
+            { rbacRoles: after },
+          );
+        }
+        const { code, expiresAt } = await createConnectorCode(
+          userId,
+          DEFAULT_INVITE_CODE_LABEL,
+          actor,
+          new Date(),
+          { kind: "invite", ttlMs: INVITE_CODE_TTL_MS },
+        );
+        return { userId, code, expiresAt };
+      });
+    } catch (err) {
+      if (err instanceof InviteUserExistsError) {
+        jsonError(res, "user_exists", 409);
+        return true;
+      }
+      // Never echo the error: it must not carry the code or the link.
+      jsonError(res, "Failed to create invite", 500);
+      return true;
+    }
+
+    const apiUrl = await resolveMcpBaseUrl();
+    const appUrl = (await resolveAppUrl()) ?? DEFAULT_APP_URL;
+    const inviteUrl = `${apiUrl}/invite/${invited.code}`;
+    createInviteRoute.respond(res, 201, {
+      user: await composeUser(invited.userId),
+      inviteUrl,
+      appUrl,
+      expiresAt: invited.expiresAt,
+      apiReachable: apiReachability(apiUrl),
+    });
+    return true;
+  }
+
+  // GET /invite/:code only redirects. Link previews must not consume invites.
+  if (openInviteRoute.match(req.method, pathSegments)) {
+    const parsed = await openInviteRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const { code } = parsed.params;
+    if (!/^[A-Za-z0-9_-]{16,256}$/.test(code)) {
+      jsonError(res, "code_invalid", 404);
+      return true;
+    }
+    const apiUrl = await resolveMcpBaseUrl();
+    const appUrl = (await resolveAppUrl()) ?? DEFAULT_APP_URL;
+    res.writeHead(302, {
+      Location: `${appUrl}/join?swarm=${encodeURIComponent(apiUrl)}#code=${code}`,
+      "Cache-Control": "no-store",
+      "Referrer-Policy": "no-referrer",
+    });
+    res.end();
+    return true;
+  }
+
+  // ─── POST /api/invites/exchange ────────────────────────────────────────────
+  if (exchangeInviteCodeRoute.match(req.method, pathSegments)) {
+    if (!inviteExchangeRateLimiter.take(clientIp(req))) {
+      res.setHeader("Retry-After", "6");
+      jsonError(res, "rate_limited", 429);
+      return true;
+    }
+    const parsed = await exchangeInviteCodeRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    // Same generated shape as connector codes; reject anything else before hashing.
+    if (!CONNECTOR_CODE_PATTERN.test(parsed.body.code)) {
+      jsonError(res, "code_invalid", 404);
+      return true;
+    }
+
+    try {
+      const result = await exchangeConnectorCode(parsed.body.code, { kind: "invite" });
+      if (!result) {
+        jsonError(res, "code_invalid", 404);
+        return true;
+      }
+      exchangeInviteCodeRoute.respond(res, 200, result);
+    } catch {
+      jsonError(res, "Failed to exchange code", 500);
+    }
+    return true;
+  }
+
   // ─── DELETE /api/users/:id/mcp-tokens/:tokenId ────────────────────────────
   if (revokeUserMcpTokenRoute.match(req.method, pathSegments)) {
     const parsed = await revokeUserMcpTokenRoute.parse(req, res, pathSegments, queryParams);

package/src/http/utils.ts

@@ -255,19 +255,38 @@ export function wireHttpSpanLifecycle(
   });
 }
 
+/**
+ * Redact invite codes and agent-fs share tokens from logs and traces.
+ * Share paths also accept the `/agentfs` proxy prefix.
+ */
+export function redactShareTokenInPath(pathname: string): string {
+  const segments = pathname.split("/");
+  if (segments[1] === "invite" && segments[2]) {
+    segments[2] = "[REDACTED]";
+    return segments.join("/");
+  }
+  const at = segments[1] === "agentfs" ? 2 : 1;
+  if ((segments[at] === "share" || segments[at] === "site") && segments[at + 1]) {
+    segments[at + 1] = "[REDACTED]";
+    return segments.join("/");
+  }
+  return pathname;
+}
+
 export function safeRequestUrlForLog(rawUrl: string | undefined): string {
   if (!rawUrl) return "";
 
   try {
     const url = new URL(rawUrl, "http://localhost");
+    const pathname = redactShareTokenInPath(url.pathname);
     const params = Array.from(url.searchParams.keys());
-    if (params.length === 0) return url.pathname;
+    if (params.length === 0) return pathname;
 
     const redactedQuery = params.map((key) => `${key}=[REDACTED]`).join("&");
-    return `${url.pathname}?${redactedQuery}`;
+    return `${pathname}?${redactedQuery}`;
   } catch {
     const pathOnly = rawUrl.split("?")[0] || rawUrl;
-    return scrubSecrets(pathOnly);
+    return scrubSecrets(redactShareTokenInPath(pathOnly));
   }
 }
 

package/src/http/workflows.ts

@@ -307,6 +307,15 @@ const triggerWorkflowRoute = route({
     "With an `Idempotency-Key`, a retry returns the accepted run's `runId` and `skipped` without starting, resuming or waiting for anything, even after the workflow was disabled or edited and whatever state the run is in now.",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
+  query: z.object({
+    wait: z
+      .enum(["true", "false"])
+      .optional()
+      .describe(
+        "Default true: respond after the run's instant steps ran, when it finishes or parks at its first async step. " +
+          "false: respond as soon as the run is committed and walk it in the background.",
+      ),
+  }),
   headers: idempotencyKeyHeader("starts one run"),
   responses: {
     201: {
@@ -1002,6 +1011,7 @@ export async function handleWorkflows(
       runId = await startWorkflowExecution(workflow, body, getExecutorRegistry(), {
         triggerType: "api",
         requestedByUserId: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+        detach: parsed.query.wait === "false",
         // Recorded in the run's own transaction, before the walk starts.
         accept: claim
           ? async (run) => {

package/src/http/x.ts

@@ -20,6 +20,7 @@ import {
   MAX_SCRIPT_WALL_CLOCK_MS,
   MIN_SCRIPT_WALL_CLOCK_MS,
 } from "../scripts-runtime/executors/types";
+import { HOST_VALIDATED_ARGS } from "../scripts-runtime/host-validated-args";
 import type { RunScriptOutput } from "../scripts-runtime/loader";
 import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 import { validateJsonSchema } from "../workflows/json-schema-validator";
@@ -214,6 +215,7 @@ export async function handleX(
   // Scripts predating the schema column, or where extraction failed, have a
   // null schema — we skip and let the in-subprocess Zod check surface as a
   // runtime_error instead.
+  let hostValidatedArgs = false;
   if (script.argsJsonSchema) {
     try {
       const schema = JSON.parse(script.argsJsonSchema) as Record<string, unknown>;
@@ -227,6 +229,7 @@ export async function handleX(
         });
         return true;
       }
+      hostValidatedArgs = true;
     } catch {
       // Malformed stored schema — don't block execution on it.
     }
@@ -245,7 +248,9 @@ export async function handleX(
   const output = await runScriptWithRunCredential({
     source: script.source,
     args: args ?? null,
+    [HOST_VALIDATED_ARGS]: hostValidatedArgs,
     fsMode: "none",
+    executor: script.executor,
     agentId: endpoint.agentId,
     // timeoutMs only raises the wall-clock limit (network-bound scripts can use
     // the full window); the CPU ulimit (`ulimit -t`) is intentionally left at

package/src/prompts/base-prompt.ts

@@ -22,6 +22,7 @@
 import type { ProviderTraits } from "../providers/types";
 import { getSlackConfiguration } from "../slack/config";
 import type { ProviderName } from "../types";
+import { resolveAgentFsLinkBase } from "../utils/constants";
 import { isSteeringEnabled } from "../utils/steering-enabled";
 import { matchesDefaultClaudeMd, matchesDefaultIdentityMd } from "./defaults";
 import { resolveTemplateAsync } from "./resolver";
@@ -74,6 +75,26 @@ function claudeMdSourcePath(provider: string): string {
 /** Providers that get the repo CLAUDE.md inlined until native loading is verified. */
 const REPO_CLAUDE_MD_INLINE_PROVIDERS: ReadonlySet<string> = new Set(["opencode"]);
 
+/**
+ * Template event for the tool-discovery line. Amp, Codex and OpenCode run MCP
+ * tools inside their own code sandbox (`code_exec`, `exec`, `execute`), each
+ * with its own call shape, so the generic lines are wrong for them.
+ */
+function toolDiscoveryEvent(provider: string, hasToolSearch: boolean): string {
+  switch (provider) {
+    case "amp":
+      return "system.agent.tool_discovery.amp";
+    case "codex":
+      return "system.agent.tool_discovery.codex";
+    case "opencode":
+      return "system.agent.tool_discovery.opencode";
+    default:
+      return hasToolSearch
+        ? "system.agent.tool_discovery.search"
+        : "system.agent.tool_discovery.direct";
+  }
+}
+
 export function areSlackPromptToolsEnabled(
   env: NodeJS.ProcessEnv = process.env,
   serverCapabilities?: string[],
@@ -229,7 +250,8 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
     const agentFsConfigured = hasLocalEnv && Boolean(process.env.AGENT_FS_API_URL);
     const outputsResult = await resolveTemplateAsync(
       agentFsConfigured ? "system.agent.outputs" : "system.agent.outputs.no_agent_fs",
-      {},
+      // Unset AGENT_FS_LINK_TARGET keeps the literal the agent expands in its shell.
+      { fileLinkBase: resolveAgentFsLinkBase("prompt") ?? `\${AGENT_FS_LIVE_URL}` },
     );
     prompt += outputsResult.text;
   }
@@ -257,26 +279,29 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
 
   // I. Tools and skills. Skipped without MCP: the discovery tools are MCP tools.
   if (hasMcp) {
-    // Amp's MCP tools sit behind its own `tool_search` + `code_exec` with
-    // underscored names, so the generic "load with your tool search" line is not enough.
-    const discoveryEvent =
-      provider === "amp"
-        ? "system.agent.tool_discovery.amp"
-        : hasToolSearch
-          ? "system.agent.tool_discovery.search"
-          : "system.agent.tool_discovery.direct";
+    const discoveryEvent = toolDiscoveryEvent(provider, hasToolSearch);
     const discoveryResult = await resolveTemplateAsync(discoveryEvent, {});
     const toolsResult = await resolveTemplateAsync(
       "system.agent.tools_skills",
       renderToolsAndSkillsVars({
         skillsSummary: args.skillsSummary,
         mcpServers: args.mcpServers,
+        // pi defers installed MCP servers together with swarm tools.
+        mcpToolsDeferred: provider === "pi" && hasToolSearch,
         nativeSkillDiscovery,
         toolDiscovery: discoveryResult.text,
         hasLocalEnv,
       }),
     );
     prompt += toolsResult.text;
+
+    // Lead docs pointer: only when the lead has the `swarm-docs` skill. The
+    // skill list is unknown on claude-managed (the cloud sandbox owns skill
+    // delivery) and before the first skill load, so render it then.
+    if (role === "lead" && hasSwarmDocsSkill(args.skillsSummary)) {
+      const docsResult = await resolveTemplateAsync("system.agent.lead.docs", {});
+      prompt += docsResult.text;
+    }
   }
 
   // J. Agent notes (CLAUDE.md), only when it differs from the generated
@@ -339,6 +364,11 @@ export const getTaskContextPrompt = async (args: TaskContextPromptArgs): Promise
   return prompt.replace(/\n{3,}/g, "\n\n").trim();
 };
 
+/** True when the skill list includes `swarm-docs`, or when the list is unknown. */
+function hasSwarmDocsSkill(skills: { name: string }[] | undefined): boolean {
+  return skills === undefined || skills.some((skill) => skill.name === "swarm-docs");
+}
+
 /**
  * Dynamic lines for `system.agent.tools_skills`. The static text lives in the
  * template so operators can override or skip the section; only the lists that
@@ -347,6 +377,7 @@ export const getTaskContextPrompt = async (args: TaskContextPromptArgs): Promise
 function renderToolsAndSkillsVars(input: {
   skillsSummary?: { name: string; description: string }[];
   mcpServers?: string[];
+  mcpToolsDeferred?: boolean;
   nativeSkillDiscovery: boolean;
   hasLocalEnv: boolean;
   toolDiscovery: string;
@@ -382,7 +413,11 @@ function renderToolsAndSkillsVars(input: {
   const servers = (input.mcpServers ?? []).filter((name) => name.trim().length > 0);
   const mcpLine =
     servers.length > 0
-      ? `Connected MCP servers: ${servers.join(", ")}. Their tools are in your tool list.\n`
+      ? `Connected MCP servers: ${servers.join(", ")}. ${
+          input.mcpToolsDeferred
+            ? "Load their tools with your harness tool search."
+            : "Their tools are in your tool list."
+        }\n`
       : "";
 
   return {

package/src/prompts/session-templates.ts

@@ -15,8 +15,9 @@
  *   G  secrets                 system.agent.secrets
  *
  * Deployment-gated blocks (E outputs, H slack, steering) and the per-agent and
- * per-task sections (tools and skills, agent notes, repository, requester
- * profile) are appended by base-prompt.ts after the composite.
+ * per-task sections (tools and skills, the lead docs pointer, agent notes,
+ * repository, requester profile) are appended by base-prompt.ts after the
+ * composite.
  *
  * Writing rules for every body: sentence case headings, one idea per sentence,
  * active voice, plain words, no em dashes, a prohibition only where no positive
@@ -109,6 +110,19 @@ Your heartbeat runbook is the \`heartbeatMd\` profile field. Edit it with \`upda
   category: "system",
 });
 
+// Lead docs pointer. base-prompt.ts appends it after the tools and skills
+// section when the lead has the `swarm-docs` skill (or when the skill list is
+// unknown). An operator override with an empty body switches it off.
+registerTemplate({
+  eventType: "system.agent.lead.docs",
+  header: "",
+  defaultBody: `
+Load the \`swarm-docs\` skill only when a person asks for something no skill, workflow, schedule or memory of yours covers, or asks where something is documented. Then follow its offer rules.
+`,
+  variables: [],
+  category: "system",
+});
+
 // Remote providers (no MCP, no container): the task arrives in the session
 // prompt and the final message is the output. No tools to name.
 registerTemplate({
@@ -168,7 +182,7 @@ registerTemplate({
 ## Memory
 
 Memories from past sessions are in your task message. Read them before you start. For a wider search, run the \`task-context-gathering\` script with the task ID and two to four queries.
-Store a learning with \`memory-store\` when you solve something that will come back: a fix, a pattern, a gotcha. Completed task outputs are stored for you.
+When you learn something that would change how the next agent works (a fix, a pattern, a gotcha), pass it as \`learning\` on a \`store-progress\` call before the task ends. Completed task outputs are stored for you.
 You MUST use the \`memory\` skill before you store, edit, or delete a memory.
 `,
   variables: [],
@@ -202,9 +216,15 @@ agent-fs is the shared drive between agents and people. Documents (reports, dige
 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.
 Link env: \`APP_URL\` for pages, \`MCP_BASE_URL\` for the API, \`AGENT_FS_LIVE_URL\` for files. Report missing variables.
-Give people the live app link \`\${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>\`. Make an \`agent-fs share-create\` link only when the requester asks for one or the reader has no agent-fs login.
+Give people the live app link \`{{fileLinkBase}}/file/~/<org>/<drive>/<path>\`. Make an \`agent-fs share-create\` link only when the requester asks for one or the reader has no agent-fs login.
 `,
-  variables: [],
+  variables: [
+    {
+      name: "fileLinkBase",
+      description:
+        "Base URL of people-facing file links (AGENT_FS_LINK_TARGET); the literal AGENT_FS_LIVE_URL shell reference when unset",
+    },
+  ],
   category: "system",
 });
 
@@ -428,6 +448,24 @@ registerTemplate({
   category: "system",
 });
 
+registerTemplate({
+  eventType: "system.agent.tool_discovery.codex",
+  header: "",
+  defaultBody:
+    "Swarm tools are not in your tool list. Call them from `exec` on the `tools` object, with dashes turned into underscores: `store-progress` is `await tools.mcp__agent_swarm__store_progress({ ... })`. Call a tool you know by that name directly. To find one, filter `ALL_TOOLS` by `name` and `description`.",
+  variables: [],
+  category: "system",
+});
+
+registerTemplate({
+  eventType: "system.agent.tool_discovery.opencode",
+  header: "",
+  defaultBody:
+    'Swarm tools are not in your tool list. Call them from `execute` under `tools.swarm`, by their exact names: `store-progress` is `await tools.swarm["store-progress"]({ ... })`. To find one, use `search({ query })` inside `execute`.',
+  variables: [],
+  category: "system",
+});
+
 registerTemplate({
   eventType: "system.agent.tool_discovery.direct",
   header: "",

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.1792929650-g000512";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1793073650-g23dd39";
 
 /** 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/codex-adapter.ts

@@ -1613,8 +1613,13 @@ export class CodexSession implements ProviderSession {
       "invalid 'refresh_token'",
     ];
     if (authPatterns.some((p) => normalized.includes(p))) {
+      const slot = this.config.codexSlot;
+      const guidance =
+        slot === undefined
+          ? "Codex authentication failed — check OPENAI_API_KEY or ChatGPT login."
+          : `Codex pool slot ${slot} authentication failed — re-run agent-swarm codex-login --slot ${slot}.`;
       return {
-        message: `[auth-error] Codex authentication failed — check OPENAI_API_KEY or ChatGPT login. Original error: ${raw}`,
+        message: `[auth-error] ${guidance} Original error: ${raw}`,
         category: "authentication_failed",
       };
     }

package/src/providers/cursor-adapter.ts

@@ -35,7 +35,7 @@ import type {
 } from "./types";
 
 /** Pinned in package.json and Dockerfile.worker; bump all three together. */
-export const CURSOR_SDK_VERSION = "1.0.40";
+export const CURSOR_SDK_VERSION = "1.1.0";
 
 /** MCP server name; Cursor reports its tools as `mcp` calls with this `providerIdentifier`. */
 const CURSOR_MCP_SERVER_NAME = "agent-swarm";