@desplega.ai/agent-swarm 1.164.1 → 1.166.0

package/src/http/ip-rate-limit.ts

@@ -0,0 +1,82 @@
+/**
+ * Small in-memory per-IP token bucket for unauthenticated routes. State is
+ * per process and resets on restart, which is fine for defense-in-depth on
+ * routes whose credential is already unguessable.
+ */
+
+import type { IncomingMessage } from "node:http";
+
+/** Bucket count that triggers a prune of idle buckets. */
+const PRUNE_THRESHOLD = 10_000;
+/** Minimum time between prunes, so a flood of new IPs cannot force a scan per request. */
+const PRUNE_INTERVAL_MS = 60_000;
+/** Hard cap on tracked buckets. New keys past it evict the oldest-inserted bucket in O(1). */
+const MAX_BUCKETS = 50_000;
+
+/** Loopback, RFC1918, link-local and IPv6 unique-local addresses (IPv4-mapped forms included). */
+function isPrivateAddress(address: string): boolean {
+  const ip = address.startsWith("::ffff:") ? address.slice(7) : address;
+  if (ip === "::1" || ip.startsWith("127.") || ip.startsWith("10.")) return true;
+  if (ip.startsWith("192.168.") || ip.startsWith("169.254.")) return true;
+  const match = /^172\.(\d+)\./.exec(ip);
+  if (match && Number(match[1]) >= 16 && Number(match[1]) <= 31) return true;
+  const lower = ip.toLowerCase();
+  return lower.startsWith("fc") || lower.startsWith("fd") || lower.startsWith("fe80:");
+}
+
+/**
+ * Client IP for rate limiting. The rightmost `X-Forwarded-For` hop (the
+ * address the nearest proxy saw) is trusted only when the socket peer is a
+ * private address, i.e. a reverse proxy on the same host or network. A client
+ * that reaches the API directly is keyed on its socket address, so a spoofed
+ * header cannot buy it a fresh bucket.
+ */
+export function clientIp(req: IncomingMessage): string {
+  const peer = req.socket.remoteAddress ?? "unknown";
+  if (!isPrivateAddress(peer)) return peer;
+  const raw = req.headers["x-forwarded-for"];
+  const header = Array.isArray(raw) ? raw[raw.length - 1] : raw;
+  const hop = header?.split(",").pop()?.trim();
+  return hop || peer;
+}
+
+export function createIpRateLimiter(options: { capacity: number; refillPerMs: number }) {
+  const buckets = new Map<string, { tokens: number; updatedAt: number }>();
+  let lastPruneAt = 0;
+
+  function refill(bucket: { tokens: number; updatedAt: number }, now: number): void {
+    const elapsed = now - bucket.updatedAt;
+    bucket.tokens = Math.min(options.capacity, bucket.tokens + elapsed * options.refillPerMs);
+    bucket.updatedAt = now;
+  }
+
+  return {
+    /** Take one token for `ip`. Returns false when the bucket is empty. */
+    take(ip: string, now = Date.now()): boolean {
+      if (buckets.size > PRUNE_THRESHOLD && now - lastPruneAt >= PRUNE_INTERVAL_MS) {
+        lastPruneAt = now;
+        for (const [key, bucket] of buckets) {
+          refill(bucket, now);
+          if (bucket.tokens >= options.capacity) buckets.delete(key);
+        }
+      }
+      let bucket = buckets.get(ip);
+      if (!bucket) {
+        if (buckets.size >= MAX_BUCKETS) {
+          const oldest = buckets.keys().next().value;
+          if (oldest !== undefined) buckets.delete(oldest);
+        }
+        bucket = { tokens: options.capacity, updatedAt: now };
+        buckets.set(ip, bucket);
+      }
+      refill(bucket, now);
+      if (bucket.tokens < 1) return false;
+      bucket.tokens -= 1;
+      return true;
+    },
+    reset(): void {
+      buckets.clear();
+      lastPruneAt = 0;
+    },
+  };
+}

package/src/http/kv.ts

@@ -13,6 +13,7 @@ import {
 } from "../be/db";
 import { mcpOverflowAuthError } from "../kv-overflow";
 import { reservedNamespaceError, reservedRoomKeyError } from "../kv-reserved-namespaces";
+import { hasKvViewArgs, resolveKvView } from "../kv-view";
 import { can } from "../rbac";
 import { agentContextKey, pageContextKey } from "../tasks/context-key";
 import { KvEntrySchema, KvKeySchema, KvNamespaceSchema, KvValueTypeSchema } from "../types";
@@ -69,12 +70,33 @@ const kvListQuerySchema = z.object({
   offset: z.coerce.number().int().nonnegative().optional(),
 });
 
+// Targeted read of one entry: dot path into a JSON value + offset/limit page.
+// Unbounded by design: these routes back ctx.swarm.kv_get inside the script
+// sandbox; the model-facing kv-get MCP tool applies its own size cap.
+const kvGetQuerySchema = z.object({
+  path: z.string().max(1024).optional(),
+  offset: z.coerce.number().int().nonnegative().optional(),
+  limit: z.coerce.number().int().positive().optional(),
+});
+
+const kvViewSchema = z.object({
+  path: z.string(),
+  type: z.enum(["object", "array", "string", "number", "boolean", "null"]),
+  total: z.number().int().nonnegative().optional(),
+  offset: z.number().int().nonnegative().optional(),
+  returned: z.number().int().nonnegative().optional(),
+  nextOffset: z.number().int().nonnegative().nullable().optional(),
+});
+
+// With path/offset/limit, `value` is the resolved slice and `view` describes it.
+const kvEntryViewSchema = KvEntrySchema.extend({ view: kvViewSchema.optional() });
+
 // ─── Routes ──────────────────────────────────────────────────────────────────
 
 const RESPONSES_GET = {
-  200: { description: "KV entry", schema: KvEntrySchema },
+  200: { description: "KV entry (or a path/offset/limit view of it)", schema: kvEntryViewSchema },
   404: { description: "KV entry not found or expired" },
-  400: { description: "Validation error or unresolvable namespace" },
+  400: { description: "Validation error, unresolvable namespace, or invalid view path" },
 } as const;
 
 const RESPONSES_PUT = {
@@ -106,6 +128,7 @@ const getKvHeader = route({
   summary: "Get a KV entry by key (namespace resolved from request headers)",
   tags: ["KV"],
   params: z.object({ key: KvKeySchema }),
+  query: kvGetQuerySchema,
   responses: RESPONSES_GET,
 });
 
@@ -167,6 +190,7 @@ const getKvExplicit = route({
   summary: "Get a KV entry by explicit namespace + key",
   tags: ["KV"],
   params: z.object({ namespace: KvNamespaceSchema, key: KvKeySchema }),
+  query: kvGetQuerySchema,
   responses: RESPONSES_GET,
 });
 
@@ -471,7 +495,7 @@ export async function handleKv(
     if (!ns) return true;
     const key = decodeKvSegment(res, parsed.params.key, "key");
     if (!key) return true;
-    return sendGet(req, res, ns, key, getKvExplicit.respond);
+    return sendGet(req, res, ns, key, parsed.query, getKvExplicit.respond);
   }
   if (putKvExplicit.match(req.method, pathSegments)) {
     if (enforceContentLengthCap(req, res, MAX_KV_BODY_BYTES) === BODY_TOO_LARGE) return true;
@@ -511,7 +535,7 @@ export async function handleKv(
     }
     const key = decodeKvSegment(res, parsed.params.key, "key");
     if (!key) return true;
-    return sendGet(req, res, ns, key, getKvHeader.respond);
+    return sendGet(req, res, ns, key, parsed.query, getKvHeader.respond);
   }
   if (putKvHeader.match(req.method, pathSegments)) {
     if (enforceContentLengthCap(req, res, MAX_KV_BODY_BYTES) === BODY_TOO_LARGE) return true;
@@ -638,6 +662,7 @@ async function sendGet(
   res: ServerResponse,
   namespace: string,
   key: string,
+  query: z.infer<typeof kvGetQuerySchema>,
   respond: GetKvRespond,
 ): Promise<boolean> {
   const authErr = authorizeRead(namespace, await buildAuthCtx(req));
@@ -650,6 +675,15 @@ async function sendGet(
     jsonError(res, "not found", 404);
     return true;
   }
+  if (hasKvViewArgs(query)) {
+    const view = resolveKvView(entry.value, query);
+    if (!view.ok) {
+      jsonError(res, view.error, 400);
+      return true;
+    }
+    respond(res, 200, { ...entry, value: view.value, view: view.view });
+    return true;
+  }
   respond(res, 200, entry);
   return true;
 }

package/src/http/mcp-servers.ts

@@ -253,6 +253,7 @@ async function mcpServerPrincipal(req: IncomingMessage): Promise<RbacPrincipal>
   const auth = getRequestAuth(req);
   if (auth?.kind === "operator") return { kind: "operator" };
   if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
+  if (auth?.kind === "guest") return { kind: "guest" };
   return { kind: "agent", agentId: "", isLead: false };
 }
 

package/src/http/memory.ts

@@ -43,6 +43,7 @@ import { can, type RbacPrincipal } from "../rbac";
 import { AgentMemorySchema, AgentMemoryScopeSchema, AgentMemorySourceSchema } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { rejectGuest } from "./request-principal";
 import { route } from "./route-def";
 import { jsonError, parseQueryParams } from "./utils";
 
@@ -108,6 +109,8 @@ const MemorySearchResultItemSchema = z.object({
   scope: AgentMemoryScopeSchema,
   tags: z.array(z.string()),
   accessCount: z.number(),
+  summary: z.string().nullable().optional(),
+  createdAt: z.string().optional(),
 });
 
 const searchMemory = route({
@@ -787,6 +790,7 @@ async function ingestPrincipal(
 ): Promise<RbacPrincipal> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
+  if (auth?.kind === "guest") return { kind: "guest" };
   const agentId = auth?.kind === "agent" ? auth.agentId : agentIdHeader;
   if (agentId) {
     const agent = await getAgentById(agentId);
@@ -810,6 +814,9 @@ export async function handleMemory(
 ): Promise<boolean> {
   // Page memory operations use the owner's scope. Authentication and audit retain the signed viewer.
   const myAgentId = getRequestAuth(req)?.page?.executionAgentId ?? callerAgentId;
+  if (pathSegments[0] === "api" && pathSegments[1] === "memory" && rejectGuest(req, res)) {
+    return true;
+  }
   if (indexMemory.match(req.method, pathSegments)) {
     const parsed = await indexMemory.parse(req, res, pathSegments, new URLSearchParams());
     if (!parsed) return true;
@@ -996,6 +1003,8 @@ export async function handleMemory(
           scope: r.scope,
           tags: r.tags,
           accessCount: (r.accessCount ?? 0) + (consumedIdSet.has(r.id) ? 1 : 0),
+          summary: r.summary,
+          createdAt: r.createdAt,
         })),
       });
     } catch (err) {

package/src/http/models-catalog.ts

@@ -275,6 +275,8 @@ async function ensureCatalogWriter(
   let principal: RbacPrincipal;
   if (auth?.kind === "user") {
     principal = { kind: "user", userId: auth.userId };
+  } else if (auth?.kind === "guest") {
+    principal = { kind: "guest" };
   } else if (agentId) {
     // An X-Agent-ID wins over the shared API key: a worker holds that key, so treating it as the
     // operator would let any worker skip the verb's lead-only rule.

package/src/http/operator-actor.ts

@@ -48,6 +48,10 @@ export function getOperatorActor(req: IncomingMessage, res: ServerResponse): Ide
   if (auth?.kind === "operator") {
     return { kind: "operator", id: auth.fingerprint };
   }
+  if (auth?.kind === "guest") {
+    jsonError(res, "Forbidden", 403);
+    return null;
+  }
 
   const rawKey = extractBearer(req);
   const swarmKey = getApiKey();

package/src/http/page-proxy.ts

@@ -149,6 +149,22 @@ function isSafeProxySuffix(suffix: string): boolean {
   return true;
 }
 
+/**
+ * What a guest page session (a password-page cookie with no signed-in user) may
+ * reach. Everything else is refused before it is forwarded:
+ *   - `GET pages/<its own id>`: the page reads its own record.
+ *   - `kv`, `kv/*`: the page's key-value store. The KV handler pins every such
+ *     request to `task:page:<own id>` through the `X-Page-Id` header set below.
+ * Exported for tests.
+ */
+export function isGuestAllowedProxyPath(method: string, suffix: string, pageId: string): boolean {
+  const segments = suffix.split("/").map((seg) => decodeURIComponent(seg));
+  if (segments[0] === "kv") return true;
+  return (
+    method === "GET" && segments.length === 2 && segments[0] === "pages" && segments[1] === pageId
+  );
+}
+
 /**
  * Handle `/@swarm/api/*` requests. Returns `true` if the request was handled
  * (response sent), `false` if not — caller continues to the next handler.
@@ -194,6 +210,12 @@ export async function handlePageProxy(req: IncomingMessage, res: ServerResponse)
     return true;
   }
 
+  // A password-page session carries no user, so only the allowlist above is reachable.
+  if (!payload.uid && !payload.op && !isGuestAllowedProxyPath(method, suffix, page.id)) {
+    jsonError(res, "forbidden", 403);
+    return true;
+  }
+
   // ─── Rewrite + forward ─────────────────────────────────────────────────────
   // `/@swarm/api/me` → `/api/me`. Preserve query string.
   //

package/src/http/pages.ts

@@ -660,7 +660,9 @@ export async function handlePages(
     }
     const favoriteScope = (await resolveHttpFavoriteOwner(req, myAgentId))?.scope;
     const [decorated] = await withFavoriteFlags([page], { favoriteScope, itemType: "page" });
-    getPageRoute.respond(res, 200, withShareUrls(decorated ?? page));
+    const body = withShareUrls(decorated ?? page);
+    if (getRequestAuth(req)?.kind === "guest") delete body.passwordHash;
+    getPageRoute.respond(res, 200, body);
     return true;
   }
 
@@ -808,7 +810,7 @@ export async function handlePages(
       auth?.kind === "user"
         ? { uid: auth.userId, name: auth.user.name }
         : auth?.kind === "operator"
-          ? { name: `guest-${randomUUID().slice(0, 8)}` }
+          ? { name: `guest-${randomUUID().slice(0, 8)}`, op: true as const }
           : undefined;
     const cookie = await issuePageSessionCookie(page.id, {
       dev: isDevRequest(req),

package/src/http/realtime.ts

@@ -53,7 +53,7 @@ export async function handleRealtimeTicket(
   const parsed = await realtimeTicketRoute.parse(req, res, pathSegments, queryParams);
   if (!parsed) return true;
   const auth = getRequestAuth(req);
-  if (!auth || auth.kind === "agent") {
+  if (!auth || auth.kind === "agent" || auth.kind === "guest") {
     jsonError(res, "Comb presence requires dashboard authentication", 403);
     return true;
   }

package/src/http/request-principal.ts

@@ -1,7 +1,8 @@
-import type { IncomingMessage } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
 import { getAgentById } from "../be/db";
 import type { RbacPrincipal } from "../rbac";
 import { getRequestAuth } from "../utils/request-auth-context";
+import { jsonError } from "./utils";
 
 /**
  * The RBAC principal of an HTTP request, for a handler-side `can()` check.
@@ -16,6 +17,7 @@ export async function requestPrincipal(
   const auth = getRequestAuth(req);
   if (auth?.kind === "operator") return { kind: "operator" };
   if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
+  if (auth?.kind === "guest") return { kind: "guest" };
   if (!myAgentId) return null;
   const agent = await getAgentById(myAgentId);
   return { kind: "agent", agentId: myAgentId, isLead: agent?.isLead ?? false };
@@ -34,8 +36,19 @@ export async function agentFirstPrincipal(
 ): Promise<RbacPrincipal> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
+  if (auth?.kind === "guest") return { kind: "guest" };
   const agentId = auth?.kind === "agent" ? auth.agentId : myAgentId;
   if (!agentId) return { kind: "operator" };
   const agent = await getAgentById(agentId);
   return { kind: "agent", agentId, isLead: agent?.isLead === true };
 }
+
+/**
+ * Refuse a guest page session on a handler that has no per-route guest rule.
+ * Writes a 403 and returns true when the request is a guest's.
+ */
+export function rejectGuest(req: IncomingMessage, res: ServerResponse): boolean {
+  if (getRequestAuth(req)?.kind !== "guest") return false;
+  jsonError(res, "Forbidden", 403);
+  return true;
+}

package/src/http/script-connections.ts

@@ -1047,6 +1047,10 @@ async function ensureConnectionAdmin(
 ): Promise<boolean> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "operator" || auth?.kind === "user") return true;
+  if (auth?.kind === "guest") {
+    jsonError(res, "Forbidden", 403);
+    return false;
+  }
 
   const callerAgentId = agentId ?? singleHeader(req, "x-agent-id");
   const agent = callerAgentId ? await getAgentById(callerAgentId) : undefined;
@@ -1081,6 +1085,10 @@ async function ensureVerbAdmin(
 ): Promise<boolean> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "operator" || auth?.kind === "user") return true;
+  if (auth?.kind === "guest") {
+    jsonError(res, "Forbidden", 403);
+    return false;
+  }
 
   const callerAgentId = agentId ?? singleHeader(req, "x-agent-id");
   const agent = callerAgentId ? await getAgentById(callerAgentId) : undefined;

package/src/http/script-runs.ts

@@ -23,6 +23,7 @@ import {
   upsertScriptRunJournalStep,
 } from "../be/db";
 import { explicitModelErrorForAgent } from "../be/model-validation";
+import { refuseSourceWithSecrets } from "../be/scripts/source-secrets";
 import { lintWorkflowLabels } from "../script-workflows/label-lint";
 import { scriptRunMaxAgentTasks, scriptRunMaxSteps } from "../script-workflows/limits";
 import {
@@ -39,14 +40,15 @@ import {
   ScriptRunStatusSchema,
   TERMINAL_SCRIPT_RUN_STATUSES,
 } from "../types";
-import { getAppUrl } from "../utils/constants";
+import { getAppUrl, getMcpBaseUrl } from "../utils/constants";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import {
   executeRawLlm,
   RawLlmConfigSchema,
   RawLlmOutputSchema,
 } from "../workflows/executors/raw-llm";
 import { route } from "./route-def";
-import { deriveApiBaseUrl, json, jsonError } from "./utils";
+import { json, jsonError } from "./utils";
 
 const DEFAULT_SCRIPT_RUN_CONCURRENCY_CAP = 10;
 
@@ -369,6 +371,12 @@ export async function handleScriptRuns(
     const agent = await requireAgent(res, agentId);
     if (!agent) return true;
 
+    const secretRefusal = refuseSourceWithSecrets(parsed.body.source);
+    if (secretRefusal) {
+      json(res, secretRefusal, 400);
+      return true;
+    }
+
     const lint = lintWorkflowLabels(parsed.body.source);
     if (!lint.ok) {
       json(
@@ -418,7 +426,7 @@ export async function handleScriptRuns(
     const { run, existing } = creation;
 
     if (!existing && parsed.body.background) {
-      startScriptRunProcess(run, deriveApiBaseUrl(req), bearerToken(req)).catch(async (err) => {
+      startScriptRunProcess(run, getMcpBaseUrl(), bearerToken(req)).catch(async (err) => {
         await updateScriptRun(run.id, {
           status: "failed",
           pid: null,
@@ -545,7 +553,7 @@ export async function handleScriptRuns(
         config: parsed.body.config ?? {},
         status: parsed.body.status,
         result: parsed.body.result,
-        error: parsed.body.error,
+        error: parsed.body.error === undefined ? undefined : scrubSecrets(parsed.body.error),
         durationMs: parsed.body.durationMs,
       });
       return assertRunWithinLimits(run.id);

package/src/http/scripts.ts

@@ -32,6 +32,7 @@ import {
 } from "../be/scripts/db";
 import { searchScripts } from "../be/scripts/embeddings";
 import { extractArgsJsonSchema } from "../be/scripts/extract-schema";
+import { refuseSourceWithSecrets } from "../be/scripts/source-secrets";
 import {
   scriptSdkTypesWithGeneratedApis,
   scriptStdlibTypesWithGeneratedApis,
@@ -649,6 +650,12 @@ export async function handleScripts(
       }
     }
 
+    const secretRefusal = refuseSourceWithSecrets(parsed.body.source);
+    if (secretRefusal) {
+      json(res, secretRefusal, 400);
+      return true;
+    }
+
     const typecheck = await typecheckScript(parsed.body.source, { agentId: agent.id });
     if (!typecheck.ok) {
       json(
@@ -716,6 +723,14 @@ export async function handleScripts(
       req.headers["x-runtime-instance-id"],
     );
 
+    // Inline source is saved as a scratch script and recorded on the run row:
+    // refuse an embedded secret before it executes or persists.
+    const secretRefusal = parsed.body.source ? refuseSourceWithSecrets(parsed.body.source) : null;
+    if (secretRefusal) {
+      json(res, secretRefusal, 400);
+      return true;
+    }
+
     let source = parsed.body.source;
     let fsMode = parsed.body.fsMode;
     let namedScript: ScriptRecord | null = null;

package/src/http/session-cost-recompute.ts

@@ -185,8 +185,9 @@ export async function recomputeSessionCost(
   // Amp's own recorded cost (`amp threads usage`) is what it billed, including
   // subagent threads the token counts miss. The adapter sends it only when
   // every request was billed through Amp, so it wins over the token price,
-  // which still fills the per-model breakdown.
-  if (input.provider === "amp" && input.harnessCostUsd > 0) {
+  // which still fills the per-model breakdown. Grok's `costUsdTicks` is the
+  // same kind of report: what xAI billed, long-context tiers included.
+  if ((input.provider === "amp" || input.provider === "grok") && input.harnessCostUsd > 0) {
     const priced = await recomputeSessionCost({ ...input, harnessCostUsd: 0 }, lookupRate);
     return {
       totalCostUsd: input.harnessCostUsd,

package/src/http/tasks.ts

@@ -75,6 +75,7 @@ import {
 import { ensure } from "../utils/business-use";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { rejectGuest } from "./request-principal";
 import { route } from "./route-def";
 import { jsonError, parseBody } from "./utils";
 
@@ -713,6 +714,8 @@ async function canSteerTask(
   } else if (auth?.kind === "user") {
     principal = { kind: "user", userId: auth.userId };
     verb = "task.steer.own";
+  } else if (auth?.kind === "guest") {
+    return false;
   } else {
     if (!myAgentId) return false;
     const agent = await getAgentById(myAgentId);
@@ -750,6 +753,8 @@ async function canActOnOwnTask(
     principal = { kind: "operator" };
   } else if (auth?.kind === "user") {
     principal = { kind: "user", userId: auth.userId };
+  } else if (auth?.kind === "guest") {
+    return false;
   } else {
     if (!myAgentId) return false;
     const agent = await getAgentById(myAgentId);
@@ -772,6 +777,7 @@ async function resolveTaskWritePrincipal(
 ): Promise<RbacPrincipal> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
+  if (auth?.kind === "guest") return { kind: "guest" };
   const agentId = auth?.kind === "agent" ? auth.agentId : myAgentId;
   if (!agentId) return { kind: "operator" };
   const agent = await getAgentById(agentId);
@@ -787,6 +793,9 @@ export async function handleTasks(
   queryParams: URLSearchParams,
   myAgentId: string | undefined,
 ): Promise<boolean> {
+  if (pathSegments[0] === "api" && pathSegments[1] === "tasks" && rejectGuest(req, res)) {
+    return true;
+  }
   if (listTasks.match(req.method, pathSegments)) {
     const parsed = await listTasks.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;