@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/manifests/runtime/http/response.ts

@@ -0,0 +1,162 @@
+import { evaluate } from "../templating.js";
+import { decodeDynamoJson } from "../auth/aws.js";
+
+/**
+ * Reading a response off the wire. Bytes to payloads, and nothing else.
+ *
+ * Part of the manifest runtime (DECLARATIVE_NODES.md §2): the manifest DESCRIBES the
+ * service, this half COMPUTES it. Split by concern so each piece stays readable.
+ */
+
+export interface Emission {
+  /**
+   * The output connector this fired on. Absent on a `send` row, which addresses a NODE
+   * instead of a connector and therefore has no dot on the canvas and no edge to draw.
+   */
+  emit?: string;
+  /** Target NODE id, resolved from the row's `send` template. Present only on a send row. */
+  to?: string;
+  /** Input handle on the target node. Defaults to `input`. */
+  handle?: string;
+  value: unknown;
+}
+
+/**
+ * Read a Server-Sent Events stream into parsed payloads.
+ *
+ * Reading and DECIDING are separate: this turns bytes into events, and events.ts decides
+ * what leaves the node. Keeping them apart is why the tool loop can watch the same stream
+ * for a tool call without the emission table knowing anything about tools.
+ */
+export async function readSse(res: Response, terminator: string | undefined, onPayload: (payload: any) => Promise<void>): Promise<void> {
+  const reader = res.body?.getReader();
+  if (!reader) throw new Error("response has no body to stream");
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+
+    // SSE frames are separated by a blank line; a frame's data may span lines.
+    let split: number;
+    while ((split = buffer.indexOf("\n\n")) !== -1) {
+      const frame = buffer.slice(0, split);
+      buffer = buffer.slice(split + 2);
+
+      const data = frame
+        .split("\n")
+        .filter((l) => l.startsWith("data:"))
+        .map((l) => l.slice(5).trim())
+        .join("");
+      if (!data || (terminator && data === terminator)) continue;
+
+      let payload: any;
+      try {
+        payload = JSON.parse(data);
+      } catch {
+        continue; // a keep-alive or comment frame
+      }
+
+      await onPayload(payload);
+    }
+  }
+}
+
+/**
+ * Read a settled response body, per the declared transport and encoding.
+ *
+ * `encoding` is a second axis to `transport`: transport says how the reply is FRAMED
+ * (one body, or a stream of events), encoding says how the values inside it are SPELLED.
+ * DynamoDB is JSON-framed and type-tagged, so it needs both.
+ */
+export async function readSettled(res: Response, transport: string, encoding?: string): Promise<any> {
+  if (transport === "text") return res.text();
+
+  /**
+   * THE HEADERS ARE THE ANSWER. A HEAD request has no body by definition: the size, the
+   * content type and the modified date all come back as headers and there is nothing else.
+   *
+   * Reading it as `text` gave an empty string and a manifest with no way to reach any of it,
+   * which is what makes this a transport rather than a flag. Lower-cased keys, because HTTP
+   * header names are case-insensitive and an expression asking for `content-length` should
+   * not depend on what the vendor happened to capitalise.
+   */
+  if (transport === "headers") {
+    const out: Record<string, string> = {};
+    res.headers.forEach((value, key) => {
+      out[key.toLowerCase()] = value;
+    });
+    return out;
+  }
+
+  /**
+   * XML, for the vendors that never moved. S3's list endpoints are the reason.
+   *
+   * Parsed to the same plain object shape a JSON reply would give, so an events table reads
+   * `response.ListBucketResult.Contents` either way and nothing downstream knows or cares
+   * which wire format it came from.
+   *
+   * `isArray` is the setting that matters. XML cannot distinguish one element from a list of
+   * one, so a bucket holding a SINGLE object parses `Contents` as an object while a bucket
+   * holding two parses it as an array. A manifest written against the second silently breaks
+   * on the first, and the failure only appears once a bucket happens to have one file in it.
+   * Naming the repeatable elements up front makes them always arrays.
+   */
+  if (transport === "xml") {
+    const { XMLParser } = await import("fast-xml-parser");
+    const parser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: "@",
+      isArray: (name) => XML_REPEATED.has(name),
+    });
+    return parser.parse(await res.text());
+  }
+
+  /**
+   * BYTES. Audio a model generated, an image to send on to another model, a file to store.
+   *
+   * Handed over as BASE64 rather than a Buffer or a stream, because what leaves a node
+   * travels on the event bus and through JSON: a Buffer does not survive that trip, and a
+   * stream cannot be handed to two consumers. base64 is the form every downstream thing can
+   * actually hold.
+   *
+   * `contentType` comes along because bytes without their type are unusable — the receiver
+   * has to guess whether it is holding an mp3 or a PDF — and the vendor already said.
+   */
+  if (transport === "binary") {
+    const bytes = Buffer.from(await res.arrayBuffer());
+    return {
+      base64: bytes.toString("base64"),
+      contentType: res.headers.get("content-type") || "application/octet-stream",
+      bytes: bytes.length,
+    };
+  }
+
+  const payload = await res.json().catch(() => ({}));
+  return encoding === "dynamodbJson" ? decodeDynamoJson(payload) : payload;
+}
+
+/**
+ * Elements that are a LIST even when there is one of them.
+ *
+ * Named rather than inferred, because the ambiguity is in XML itself and no parser can
+ * resolve it without being told. Add to this when a node meets a new repeatable element;
+ * getting it wrong shows up as "works with 2 files, breaks with 1".
+ */
+const XML_REPEATED = new Set(["Contents", "CommonPrefixes", "Bucket", "Version", "DeleteMarker", "member", "item"]);
+
+/**
+ * A 200 carrying an error body must not read as success.
+ *
+ * This was declared by every node and implemented on the service channel only, so on the
+ * workflow channel a failed stream emitted nothing and reported success. Same class of
+ * gap as `retry`: named in the schema, absent from the executor.
+ */
+export async function assertOk(node: unknown, call: any, payload: any, where: string): Promise<void> {
+  if (!call.error?.when) return;
+  if (!(await evaluate(call.error.when, { response: payload }))) return;
+  const message = call.error.message ? await evaluate(call.error.message, { response: payload }) : "upstream error";
+  throw new Error(`${where}: ${message}`);
+}

package/vendor/base/src/manifests/runtime/index.ts

@@ -0,0 +1,57 @@
+/**
+ * THE MANIFEST RUNTIME — the half that COMPUTES what a manifest DESCRIBES.
+ *
+ * The split (DECLARATIVE_NODES.md §2): every enum value in api.schema.json must have an
+ * implementation somewhere in this folder and NOWHERE else, which is what makes accepting a
+ * manifest from someone else safe. `manifest-capabilities.test.ts` enforces that parity by
+ * walking the schema and this tree, so a capability offered without code fails the build rather
+ * than a stranger's workflow.
+ *
+ * Nothing in here is per-vendor. Adding an auth scheme or a transport makes it available to
+ * every node that will ever be written.
+ *
+ * THIS FILE IS A BARREL and should stay one. It held the two channels, the narrator and the
+ * last-call dispatch until it reached 425 lines of four unrelated concerns, which is the shape
+ * of file nobody reads and everybody appends to. One import surface, no logic:
+ *
+ *   context.ts     what a manifest may see, and the resolvers applied first
+ *   templating.ts  {{ }} and `return ...`, both borrowed from the platform
+ *   events.ts      the events table: everything that LEAVES a node, in one ordered list
+ *   narrate.ts     the running commentary while it works
+ *   state.ts       platform storage, and the run's saved context
+ *   channels/      the two ways a node is reached, which never cross
+ *     workflow.ts  the GRAPH runs it: the shape of a run, start to finish
+ *     final.ts     the last call, the only one that may stream — one dispatch per reply shape
+ *     service.ts   an AGENT calls it: one method, one value handed straight back
+ *   http/          building and sending. One fetch, one allowedHosts check
+ *   auth/          the schemes, per scheme
+ *   loops/         many requests, or many passes, for one node: paginate, poll, chunk, loop
+ *   duplex/        a socket that stays open. Two of them: the vendor's and the audio lane
+ *   tools/         the HTTP tool exchange, by turns
+ */
+export type { RunContext } from "./context.js";
+export type { Emission } from "./http/response.js";
+export { emptyContext, applyResolvers, RESOLVERS } from "./context.js";
+export { render, evaluate, primeTemplating } from "./templating.js";
+export { assertAllowedHost } from "./http/allowedHosts.js";
+export { buildRequest, resolveBody, sendRequest, runCalls } from "./http/request.js";
+export { readSse, readSettled, assertOk } from "./http/response.js";
+export { makeStateStore, performState, type StateStore } from "./state.js";
+export { fetchPaginated } from "./loops/paginate.js";
+export { fetchPolled } from "./loops/poll.js";
+export { sendChunked } from "./loops/chunk.js";
+// Iteration bookkeeping for the LoopStart/LoopEnd pair. ONE capability rather than the seven raw
+// Redis commands the retired nodes reached for — see loops/loop.ts for why that distinction is
+// the whole point.
+export { performLoop, normaliseItems, makeLoopOps, type LoopOps, type LoopPass, type LoopStep } from "./loops/loop.js";
+export { makeEmitter, type Emitter, type EventSource } from "./events.js";
+export { makeNarrator, type Narrator } from "./narrate.js";
+export { runToolLoop, type ToolBridge } from "./tools/toolloop.js";
+export { performDoc, MUTATING_DOC_OPS, docKeyFor } from "./docstore/index.js";
+export { runDuplexSession } from "./duplex/session.js";
+// The audio lane is its own module: session.ts owns the VENDOR socket, audioLane.ts owns the bytes
+// and the browser. Two sockets, two files.
+export { resamplePcm16, makeAudioBuffer, CLIENT_RATE, type AudioLane } from "./duplex/audioLane.js";
+export { performApi, type RunResult } from "./channels/workflow.js";
+export { runFinal } from "./channels/final.js";
+export { performService } from "./channels/service.js";

package/vendor/base/src/manifests/runtime/loops/chunk.ts

@@ -0,0 +1,98 @@
+/**
+ * CHUNKED WRITES. One call in the manifest, many requests on the wire.
+ *
+ * The mirror of pagination: that one loops because the vendor decides how much comes back,
+ * this one loops because the vendor decides how much may go in at once. Airtable takes 10
+ * records per write, HubSpot 100, Salesforce 200, so writing a collection of unknown length
+ * is N requests and a manifest has no way to repeat a call N times.
+ *
+ * The loop is computation, the batch size and the body shape are description, which is the
+ * usual split. Every node that writes a collection inherits this.
+ *
+ * The reply is `{ sent, batches, results, errors }`. Partial success is the normal outcome
+ * of a batched write and it must be visible: one rejected batch out of ten is not a failed
+ * call, and it is not a successful one either.
+ */
+import type { ComposedNode } from "../../compose.js";
+import type { RunContext } from "../context.js";
+import { evaluate } from "../templating.js";
+import { sendRequest } from "../http/request.js";
+import { fetchPolled } from "./poll.js";
+import { readSettled } from "../http/response.js";
+
+export interface Chunked {
+  /** Items actually accepted, across every batch that succeeded. */
+  sent: number;
+  batches: number;
+  /**
+   * What the walk was OVER, in order — the resolved collection, not a count of it.
+   *
+   * The other four fields all describe what HAPPENED, and for a write that is the whole
+   * story. Fanning out a READ needs the input as well: pairing reply i back to the thing
+   * that produced it is impossible from a summary, and re-deriving the list in the events
+   * table means the same expression written twice, free to drift.
+   */
+  items: unknown[];
+  /**
+   * One entry per batch, IN ORDER, `null` where the batch failed.
+   *
+   * Positional, not compacted. A write only ever reads `sent`, so the difference did not
+   * show until `chunk` was used to fan out a READ (one item per request), where the caller
+   * has to pair each reply back to the item that produced it. Dropping the failures would
+   * shift every later reply onto the wrong item and label the results wrongly, which is
+   * worse than an error, because it looks like an answer.
+   */
+  results: unknown[];
+  /** One entry per FAILED batch, naming which. Empty means every batch landed. */
+  errors: string[];
+}
+
+/** Independent of anything the manifest says, so a bad `size` cannot melt a vendor. */
+const HARD_BATCH_CAP = 200;
+
+export async function sendChunked(
+  node: ComposedNode,
+  call: any,
+  ctx: RunContext,
+  label: string,
+): Promise<Chunked> {
+  const c = call.chunk;
+  const all = await evaluate(c.items, ctx as unknown as Record<string, unknown>);
+  const items: unknown[] = Array.isArray(all) ? all : [];
+  const size = Math.min(Math.max(Number(c.size) || 1, 1), HARD_BATCH_CAP);
+
+  const out: Chunked = { sent: 0, batches: 0, items, results: [], errors: [] };
+  if (!items.length) return out;
+
+  for (let i = 0; i < items.length; i += size) {
+    const batch = items.slice(i, i + size);
+    const n = out.batches + 1;
+
+    // `batch` is in scope for the body, which is the whole point: the manifest describes
+    // what ONE request looks like for a slice, and this repeats it.
+    const scoped = { ...ctx, batch } as RunContext;
+
+    try {
+      // The two loops COMPOSE, because they are orthogonal: this one walks the collection,
+      // `poll` waits on one request. A vendor whose endpoint takes a single item AND runs
+      // it as a job (Hyperbrowser's fetch is both) needs both, and declaring them mutually
+      // exclusive would put that node back in TypeScript for no reason.
+      out.results.push(
+        call.poll
+          ? await fetchPolled(node, call, scoped, `${label} (batch ${n})`)
+          : await readSettled(await sendRequest(node, call, scoped, `${label} (batch ${n})`), call.transport, call.encoding),
+      );
+      out.sent += batch.length;
+    } catch (err: any) {
+      // KEEP GOING. A batched write that abandons everything because batch 3 of 10 failed
+      // is worse than one that reports which: the first two already landed and cannot be
+      // taken back, so stopping leaves the caller unable to tell what happened.
+      out.errors.push(`batch ${n}: ${err?.message ?? err}`);
+      // Holds the slot, so `results[i]` is always the reply to batch `i`.
+      out.results.push(null);
+    }
+    out.batches = n;
+  }
+
+  return out;
+}

package/vendor/base/src/manifests/runtime/loops/loop.ts

@@ -0,0 +1,191 @@
+/**
+ * ITERATION BOOKKEEPING — the capability behind the LoopStart / LoopEnd pair.
+ *
+ * WHY THIS IS ONE CAPABILITY AND NOT SEVERAL STATE OPS. The retired executors reached for
+ * hset, hget, hincrby, rpush, lrange, exists, del and expire. Declaring those one by one in
+ * api.schema.json would have amounted to "a manifest may run arbitrary Redis", which is the
+ * exact authority this format exists to withhold (DECLARATIVE_NODES.md §2). So the manifest
+ * names the three things a loop actually DOES, and the key layout, the counter and the
+ * teardown stay in here where they can be read once and audited:
+ *
+ *   open     take an array, record it, hand back the first item
+ *   read     hand back the item at the CURRENT index, without moving it
+ *   advance  collect this pass's value, move the index, and say whether there is more
+ *
+ * THE PAIR IS NOT AN ACTOR, which is the thing to understand before changing any of this.
+ * There is no XState access and no generator: LoopStart is an ordinary settle-once node that
+ * fires on its `items` input and then fires AGAIN because LoopEnd routes a `continue` signal
+ * back to it along a real edge. Each pass is a separate execution of both nodes, which is why
+ * all the state has to live outside them — a local variable would not survive the gap.
+ *
+ * `read` and `advance` are deliberately separate so that ITEM EMISSION HAS ONE HOME. LoopEnd
+ * moves the index and LoopStart reads it; if LoopEnd also returned the next item, the same
+ * fact would be computed in two places and could disagree by one.
+ *
+ * The engine has its own stake in the output shape: `executingState.ts` lifts {item, index,
+ * total} off a node whose type is literally "LoopStart" into `activeLoop`, and that is what
+ * makes {{ loop.item }} resolve for every node inside the body. So those three names are a
+ * contract, not a preference.
+ */
+
+/** The Redis surface a loop needs. Injected, so this file touches no platform global. */
+export interface LoopOps {
+  open(executionId: string, loopId: string, items: unknown): Promise<LoopPass>;
+  read(executionId: string, loopId: string): Promise<LoopPass>;
+  advance(executionId: string, loopId: string, collect: unknown): Promise<LoopStep>;
+}
+
+/** One pass, as LoopStart emits it. The three names the engine reads. */
+export interface LoopPass {
+  item: unknown;
+  index: number;
+  total: number;
+}
+
+/** The end of one pass, as LoopEnd emits it. */
+export interface LoopStep {
+  continuing: boolean;
+  index: number;
+  total: number;
+  collected?: unknown[];
+}
+
+/** An hour, matching the retired nodes. The state is within-run; this only stops a leak. */
+const TTL_SECONDS = 3600;
+
+/**
+ * THE ITEMS INPUT, normalised — and this is executor work rather than manifest work because
+ * what it unwraps is the PLATFORM'S OWN envelope, not the shape of anyone's data.
+ *
+ * A wired input arrives nested twice, by source node id and then by that source's output
+ * handle: `{ upstream1: { rows: [...] } }`. The retired executor peeled that off, and doing it
+ * in an expression instead would mean repeating `config.items || signal.items || []` five times
+ * inside one nested ternary, because the sandbox cannot bind an intermediate. That is the
+ * FieldValidator trap, and the answer here is that the envelope belongs to us.
+ *
+ * TRANSCRIBED from LoopStart's executor, branch for branch:
+ *   an array, or anything not an object   use it as-is
+ *   one source holding an object          the first ARRAY field in it, else the object itself
+ *   one source holding anything else      that value
+ * then a non-array becomes a one-item array, so "loop over a single thing" means one pass
+ * rather than nothing.
+ */
+export function normaliseItems(raw: unknown): unknown[] {
+  let items: any = raw ?? [];
+
+  if (!Array.isArray(items) && items !== null && typeof items === "object") {
+    const firstSource = Object.values(items)[0];
+    if (firstSource && typeof firstSource === "object" && !Array.isArray(firstSource)) {
+      items = Object.values(firstSource).find((v) => Array.isArray(v)) || firstSource;
+    } else {
+      items = firstSource || [];
+    }
+  }
+
+  return Array.isArray(items) ? items : [items];
+}
+
+/**
+ * Bound to a live client. `undefined` when the platform has no Redis.
+ *
+ * KEYS ARE NAMESPACED, unlike the saved-context hash in state.ts, and the difference is about
+ * who else reads them. `saved:<executionId>` is the engine's and must stay bare. These two are
+ * ours alone, read by nothing outside this file, and both halves of the pair always move
+ * versions together — so there is no bare-versus-prefixed mismatch to create.
+ */
+export function makeLoopOps(redis: any, namespace: string | undefined): LoopOps | undefined {
+  if (!redis) return undefined;
+  const ns = namespace ? `${namespace}:` : "";
+  const stateKey = (executionId: string, loopId: string) => `${ns}loop:${executionId}:${loopId}`;
+  const collectedKey = (executionId: string, loopId: string) => `${ns}loop:collected:${executionId}:${loopId}`;
+
+  const parseItem = (raw: string): unknown => {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw; // a value stored as plain text reads back as text rather than failing the loop
+    }
+  };
+
+  return {
+    async open(executionId, loopId, items) {
+      const list = normaliseItems(items);
+      const key = stateKey(executionId, loopId);
+      await redis.hset(key, { items: JSON.stringify(list), index: "0", total: String(list.length) });
+      await redis.expire(key, TTL_SECONDS);
+      return { item: list.length ? list[0] : null, index: 0, total: list.length };
+    },
+
+    async read(executionId, loopId) {
+      const key = stateKey(executionId, loopId);
+      const [itemsJson, indexStr, totalStr] = await Promise.all([
+        redis.hget(key, "items"),
+        redis.hget(key, "index"),
+        redis.hget(key, "total"),
+      ]);
+      const list: unknown[] = JSON.parse(itemsJson || "[]");
+      const index = parseInt(indexStr || "0", 10);
+      return { item: list[index] ?? null, index, total: parseInt(totalStr || "0", 10) };
+    },
+
+    async advance(executionId, loopId, collect) {
+      const key = stateKey(executionId, loopId);
+      const bag = collectedKey(executionId, loopId);
+
+      // A MISSING LOOP IS AN ERROR, not an empty result. It means LoopEnd is pointing at a
+      // LoopStart that never ran — usually a mistyped loopStartNodeId — and returning "done"
+      // would silently complete a loop that never had a first pass.
+      if (!(await redis.exists(key))) throw new Error(`loop state not found for ${executionId}:${loopId}`);
+
+      // Empty string as well as null: `collect` is a template field, so a config left blank
+      // resolves to "" rather than to nothing, and storing that would put a blank entry in the
+      // results for every pass.
+      if (collect !== undefined && collect !== null && collect !== "") {
+        // An ARRAY IS SPREAD into separate entries rather than nested, matching the retired
+        // node: collecting a per-item list gives one flat result list at the end.
+        for (const item of Array.isArray(collect) ? collect : [collect]) await redis.rpush(bag, JSON.stringify(item));
+        await redis.expire(bag, TTL_SECONDS);
+      }
+
+      // hincrby, so two nodes finishing at once cannot both read the same index and skip one.
+      const index: number = await redis.hincrby(key, "index", 1);
+      const total = parseInt((await redis.hget(key, "total")) || "0", 10);
+      if (index < total) return { continuing: true, index, total };
+
+      const collected = (await redis.exists(bag)) ? ((await redis.lrange(bag, 0, -1)) as string[]).map(parseItem) : [];
+      // Torn down on the last pass, so a long workflow does not carry every loop it ever ran.
+      await redis.del(key, bag);
+      return { continuing: false, index, total, collected };
+    },
+  };
+}
+
+/**
+ * Perform one declared loop operation.
+ *
+ * Unlike a state read, THERE IS NO DEGRADED MODE. A cache that reads cold is a cache doing its
+ * job badly; a loop with nowhere to keep its index cannot iterate at all, and pretending
+ * otherwise would run the body once and call it done.
+ */
+export async function performLoop(
+  op: string,
+  executionId: string | undefined,
+  loopId: string,
+  value: unknown,
+  ops: LoopOps | undefined,
+): Promise<LoopPass | LoopStep> {
+  if (!ops) throw new Error(`loop "${op}" needs Redis to keep its index, and this platform has none configured`);
+  if (!executionId) throw new Error(`loop "${op}" needs the run's executionId, and this run supplied none`);
+  if (!loopId) throw new Error(`loop "${op}" needs the LoopStart node's id as its "key", and none resolved`);
+
+  switch (op) {
+    case "open":
+      return ops.open(executionId, loopId, value);
+    case "read":
+      return ops.read(executionId, loopId);
+    case "advance":
+      return ops.advance(executionId, loopId, value);
+    default:
+      throw new Error(`loop operation "${op}" is declared in the schema but not implemented in the executor`);
+  }
+}

package/vendor/base/src/manifests/runtime/loops/paginate.ts

@@ -0,0 +1,143 @@
+/**
+ * PAGINATION. One call in the manifest, many requests on the wire.
+ *
+ * Vendors disagree about the mechanism and agree about the shape: ask, get a page and a way
+ * to ask for the next, repeat until there is no next or you have enough. The disagreement
+ * is description (where the token lives, what it goes back as); the loop is computation, so
+ * it belongs here and every list-returning node inherits it (DECLARATIVE_NODES.md §2).
+ *
+ * Without this a manifest cannot express a second page at all, because it has no way to
+ * repeat a call an unknown number of times. `calls` is an ordered list of DIFFERENT calls,
+ * not a loop.
+ *
+ * A paginated call's reply is `{ items, pages, truncated }`, not the last page's body. The
+ * accumulation is the answer, and handing back the final page would quietly lose the rest.
+ */
+import type { ComposedNode } from "../../compose.js";
+import type { RunContext } from "../context.js";
+import { evaluate } from "../templating.js";
+import { sendRequest } from "../http/request.js";
+import { readSettled, assertOk } from "../http/response.js";
+
+/**
+ * Put the page token where the manifest said. Explicit on BOTH values rather than treating
+ * query as an implicit else: the capability guard reads the enum and asks the executor to
+ * name every member, which is what stops a schema value existing with no implementation.
+ */
+function place(call: any, where: string, into: string, value: unknown): any {
+  switch (where) {
+    case "query":
+      return { ...call, query: { ...(call.query ?? {}), [into]: value } };
+    case "body":
+      return { ...call, body: withBodyKey(call.body, into, value) };
+    default:
+      throw new Error(`pagination "in: ${where}" is declared in the schema but not implemented in the executor`);
+  }
+}
+
+/** Set a key on a body that may be an object OR a `return ...` expression. */
+function withBodyKey(body: any, key: string, value: unknown): any {
+  return typeof body === "string"
+    ? `return Object.assign({}, (${body.replace(/^return\s+/, "")}), ${JSON.stringify({ [key]: value })})`
+    : { ...(body ?? {}), [key]: value };
+}
+
+export interface Paginated {
+  items: unknown[];
+  pages: number;
+  /** True when a bound stopped the walk while the vendor still had more. */
+  truncated: boolean;
+}
+
+/**
+ * A hard ceiling on requests, independent of anything the manifest says.
+ *
+ * A vendor that keeps returning the same cursor, or a manifest whose `cursor` expression
+ * always finds a value, would otherwise loop until the process died. `max` is the author's
+ * bound; this is the platform's, and it exists because the author's can be wrong.
+ */
+const HARD_PAGE_CAP = 100;
+
+export async function fetchPaginated(
+  node: ComposedNode,
+  call: any,
+  ctx: RunContext,
+  label: string,
+): Promise<Paginated> {
+  const p = call.paginate;
+
+  // Branch on the declared strategy. Without this the enum would be decoration: a value
+  // added to the schema would silently walk as a cursor and look like it worked.
+  if (p.strategy !== "cursor" && p.strategy !== "page" && p.strategy !== "offset")
+    throw new Error(`pagination strategy "${p.strategy}" is declared in the schema but not implemented in the executor`);
+
+  /**
+   * UNBOUNDED IS THE DEFAULT, and it must not go through the sandbox to get there.
+   *
+   * This read `evaluate(p.max ?? "return Infinity")`, which threw `unknown identifier
+   * 'Infinity'` — the expression allowlist has no such global, by design. So EVERY
+   * paginated call that did not set `max` failed at the first page. AirtableInsert's dedup
+   * scan is one of them, in the shipped tree.
+   *
+   * It survived because the two nodes written since both happen to set `max` from config,
+   * and a default only breaks when someone takes it.
+   */
+  const max = p.max
+    ? Number(await evaluate(String(p.max), ctx as unknown as Record<string, unknown>)) || Infinity
+    : Infinity;
+
+  const items: unknown[] = [];
+  // `page` counts from 1, `offset` counts ITEMS from 0, and both go out on the first
+  // request; `cursor` is absent until a reply hands one over.
+  let cursor: unknown = p.strategy === "page" ? 1 : p.strategy === "offset" ? 0 : undefined;
+  let pages = 0;
+  let more = false;
+
+  for (; pages < HARD_PAGE_CAP; ) {
+    // The token rides on a COPY of the call, so the manifest's own keys are untouched.
+    //
+    // `in` says WHERE: a query parameter by default, or the body, because a JSON-body search
+    // endpoint takes its page number in the body and there is nowhere else to put it.
+    const spec = cursor === undefined ? call : place(call, p.in ?? "query", p.into, cursor);
+
+    const res = await sendRequest(node, spec, ctx, `${label} (page ${pages + 1})`);
+    const payload = await readSettled(res, call.transport, call.encoding);
+    await assertOk(node, call, payload, `${label} (page ${pages + 1})`);
+    pages++;
+
+    const page = await evaluate(p.items, { response: payload } as Record<string, unknown>);
+    for (const item of Array.isArray(page) ? page : []) {
+      if (items.length >= max) break;
+      items.push(item);
+    }
+
+    if (p.strategy === "page" || p.strategy === "offset") {
+      // No token to follow, so the END is a SHORT PAGE: fewer items than a full one means
+      // there is nothing after it. Both counting strategies end the same way; they differ
+      // only in what the number MEANS, and so in what it steps by.
+      //
+      //   page    an index of pages, 1, 2, 3      → step 1
+      //   offset  a count of ITEMS already seen   → step size
+      //
+      // Getting that step wrong is the quiet kind of wrong: stepping an offset by 1 re-reads
+      // the same window minus one row and the walk returns mostly duplicates.
+      const got = Array.isArray(page) ? page.length : 0;
+      const size = Number(await evaluate(String(p.size ?? "return 0"), ctx as unknown as Record<string, unknown>)) || 0;
+      if (got === 0 || (size && got < size)) return { items, pages, truncated: false };
+      cursor = Number(cursor) + (p.strategy === "offset" ? (size || got) : 1);
+    } else {
+      cursor = await evaluate(p.cursor, { response: payload } as Record<string, unknown>);
+      // A falsy cursor is the vendor saying "that was the last page".
+      if (!cursor) return { items, pages, truncated: false };
+    }
+    if (items.length >= max) {
+      more = true;
+      break;
+    }
+  }
+
+  if (pages >= HARD_PAGE_CAP)
+    console.warn(`[manifests] ${label}: stopped at the ${HARD_PAGE_CAP}-page ceiling with a cursor still present`);
+
+  return { items, pages, truncated: more || pages >= HARD_PAGE_CAP };
+}