@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/manifests/runtime/auth/aws.ts

@@ -0,0 +1,240 @@
+/**
+ * AWS Signature Version 4.
+ *
+ * THE CANONICAL CASE FOR THE WHOLE FORMAT (DECLARATIVE_NODES.md §2). Signing is
+ * computation over the request — it hashes the exact bytes being sent — so it belongs to
+ * the executor. What service to call, at what URL, with what body, is description, so it
+ * belongs to the manifest. Implement this once and DynamoDB, Bedrock, Textract and
+ * Comprehend stop being TypeScript packages.
+ *
+ * It is also why AWS "needs an SDK". Take the signer out of @aws-sdk/client-dynamodb and
+ * what remains is a JSON POST to one endpoint with a header naming the operation.
+ *
+ * NOT HAND-ROLLED, deliberately. `@smithy/signature-v4` is the same signer every AWS
+ * customer runs, and the edge cases are where this bites: canonical URI encoding differs by
+ * service (S3 does not double-encode paths, everything else does), headers must be trimmed
+ * and sorted just so, and temporary credentials add a token header that is itself signed.
+ * Getting any of them subtly wrong returns a 403, which reads as a bad credential and sends
+ * whoever sees it hunting IAM for a problem that is in here.
+ *
+ * NOTHING HERE IS PER-VENDOR IN THE AWS SENSE EITHER: this signs a request for whatever
+ * `service` the manifest names. There is no DynamoDB in this file, and there must not be.
+ */
+import { SignatureV4 } from "@smithy/signature-v4";
+import { HttpRequest } from "@smithy/protocol-http";
+import { Sha256 } from "@aws-crypto/sha256-js";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+
+export interface AwsSigning {
+  region: string;
+  service: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  /** Present only for temporary credentials (STS / assumed roles). */
+  sessionToken?: string;
+  /**
+   * Send and sign `x-amz-content-sha256`, the payload hash. Defaults to ON.
+   *
+   * S3 REQUIRES it. Every other service accepts it, and signing the payload hash
+   * explicitly is strictly safer than leaving it implicit, so ON is the right default
+   * rather than a per-service opt-in nobody would remember to set.
+   *
+   * Off exists because AWS's own published test vectors are written without it, and a
+   * signer that cannot be compared against a known-good value is a signer nobody can check.
+   */
+  applyChecksum?: boolean;
+}
+
+/**
+ * Sign a fully-built request, returning the headers to send.
+ *
+ * TAKES THE FINAL URL AND THE FINAL BODY, and that ordering is the whole subtlety. Every
+ * other auth scheme resolves before the request is assembled, because a bearer token does
+ * not depend on what it is attached to. A signature does: it covers the method, the path,
+ * the query, the headers and a hash of the body, so it cannot be computed until all of
+ * them are settled. Signing early would produce a valid-looking Authorization header for a
+ * request that was never sent.
+ */
+/**
+ * AWS-CANONICAL PATH ENCODING, the residue encodeURIComponent leaves behind.
+ *
+ * `encodeURIComponent` deliberately skips `!'()*` — legal in a URL path — but SigV4's
+ * canonical URI requires every byte outside ALPHA/DIGIT/`-._~` percent-encoded. A key like
+ * `report (final).pdf` therefore signs one string while S3 canonicalises another, and the
+ * answer is a bare 403 that a HEAD cannot even explain (no body). Encoding these five here
+ * changes nothing for keys without them and makes the signature agree for keys with them —
+ * S3 resolves `%28` and `(` to the same object either way.
+ */
+const awsCanonicalPath = (pathname: string): string =>
+  pathname.replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+
+export async function signAwsRequest(
+  url: string,
+  method: string,
+  headers: Record<string, string>,
+  body: string | undefined,
+  signing: AwsSigning,
+): Promise<Record<string, string>> {
+  const parsed = new URL(url);
+
+  const query: Record<string, string> = {};
+  parsed.searchParams.forEach((value, key) => {
+    query[key] = value;
+  });
+
+  const signer = new SignatureV4({
+    service: signing.service,
+    region: signing.region,
+    credentials: {
+      accessKeyId: signing.accessKeyId,
+      secretAccessKey: signing.secretAccessKey,
+      sessionToken: signing.sessionToken,
+    },
+    sha256: Sha256,
+    applyChecksum: signing.applyChecksum !== false,
+    /**
+     * S3 IS THE EXCEPTION, and it is the classic SigV4 bug.
+     *
+     * Every other service double-encodes the path when canonicalising it; S3 does not,
+     * because an S3 key may legitimately contain characters that a second pass would
+     * mangle. Sign an S3 request the ordinary way and any key with a space or a slash in it
+     * returns 403 while simple keys work — which reads as a permissions problem on some
+     * objects and not others.
+     */
+    uriEscapePath: signing.service !== "s3",
+  });
+
+  const signed = await signer.sign(
+    new HttpRequest({
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port ? Number(parsed.port) : undefined,
+      path: awsCanonicalPath(parsed.pathname),
+      query,
+      method: method.toUpperCase(),
+      // `host` MUST be present and MUST match what is dialled: it is a signed header, and a
+      // mismatch between the signature and the Host the server sees is a 403 with a message
+      // that does not mention hosts.
+      headers: { ...headers, host: parsed.host },
+      body,
+    }),
+  );
+
+  return signed.headers as Record<string, string>;
+}
+
+/**
+ * A PRESIGNED URL: authority to fetch one object, handed to someone who has no credentials.
+ *
+ * The signature moves out of the Authorization HEADER and into the QUERY STRING, with an
+ * expiry, so the URL alone is enough. That is what makes it shareable — a browser, an email,
+ * an LLM's answer — and also why the expiry matters: anyone holding the link has the access
+ * until it lapses.
+ *
+ * NO NETWORK. This computes a string from the credentials and the clock, which is why a
+ * manifest reaches it as a call entry that never goes out, the same way `state` does.
+ */
+export async function presignAwsUrl(
+  url: string,
+  signing: AwsSigning,
+  expiresIn: number,
+): Promise<string> {
+  const parsed = new URL(url);
+
+  const query: Record<string, string> = {};
+  parsed.searchParams.forEach((value, key) => {
+    query[key] = value;
+  });
+
+  const signer = new SignatureV4({
+    service: signing.service,
+    region: signing.region,
+    credentials: {
+      accessKeyId: signing.accessKeyId,
+      secretAccessKey: signing.secretAccessKey,
+      sessionToken: signing.sessionToken,
+    },
+    sha256: Sha256,
+    uriEscapePath: signing.service !== "s3",
+  });
+
+  const signed = await signer.presign(
+    new HttpRequest({
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port ? Number(parsed.port) : undefined,
+      path: awsCanonicalPath(parsed.pathname),
+      query,
+      method: "GET",
+      // UNSIGNED-PAYLOAD, declared as the sha256 header so the signer hoists it into the
+      // query and signs THAT. Without it the signer hashes the (absent) body to the
+      // empty-string sha, while S3 verifies a query-auth GET against UNSIGNED-PAYLOAD —
+      // a SignatureDoesNotMatch whose error mentions neither body nor payload. This is
+      // what @aws-sdk/s3-request-presigner does; proved against live S3 rather than added
+      // as a dependency for one header.
+      headers: { host: parsed.host, "x-amz-content-sha256": "UNSIGNED-PAYLOAD" },
+    }),
+    { expiresIn },
+  );
+
+  const out = new URL(`${signed.protocol}//${signed.hostname}${signed.path}`);
+  for (const [k, v] of Object.entries(signed.query ?? {})) {
+    if (typeof v === "string") out.searchParams.set(k, v);
+  }
+  return out.toString();
+}
+
+/**
+ * DynamoDB's type-tagged encoding, in and out.
+ *
+ * DynamoDB does not carry `{ name: "Ada" }`. It carries `{ name: { S: "Ada" } }` — every
+ * value tagged with its type, nested arbitrarily. Something has to translate, and it cannot
+ * be an expression: the walk is RECURSIVE and the sandbox has no way to define a function
+ * that calls itself.
+ *
+ * `@aws-sdk/util-dynamodb` is AWS's own translator for exactly this, and it is what the
+ * DocumentClient uses internally. Same judgement as the signer above: a published,
+ * widely-run implementation beats one written here, because the edge cases (binary, sets,
+ * empty strings, numeric precision) are where a hand-rolled version quietly differs.
+ *
+ * Marked ENCODING rather than transport: transport is how a reply is FRAMED (json, sse),
+ * this is how the values inside it are SPELLED. A manifest writes plain JSON either way.
+ */
+export function encodeDynamoJson(value: unknown): unknown {
+  if (value === undefined || value === null) return value;
+  if (Array.isArray(value)) return value.map(encodeDynamoJson);
+  if (typeof value !== "object") return value;
+
+  const out: Record<string, unknown> = {};
+  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+    // Only the keys that HOLD ITEM DATA are translated. The rest of a DynamoDB request is
+    // ordinary JSON — TableName is a string, Limit is a number — and marshalling those
+    // would turn `TableName: "Users"` into `{ S: "Users" }` and 400 every call.
+    out[key] = ITEM_KEYS.has(key) && v && typeof v === "object" && !Array.isArray(v)
+      ? marshall(v as Record<string, unknown>, { removeUndefinedValues: true })
+      : encodeDynamoJson(v);
+  }
+  return out;
+}
+
+/** Request keys whose value is item data, so the only ones that get type tags. */
+const ITEM_KEYS = new Set(["Item", "Key", "ExpressionAttributeValues", "ExclusiveStartKey"]);
+
+/** Reply keys that come back type-tagged. `Items` is a list, `Item` a single map. */
+const REPLY_KEYS = new Set(["Item", "Items", "Attributes", "LastEvaluatedKey", "Responses"]);
+
+export function decodeDynamoJson(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+
+  const out: Record<string, unknown> = {};
+  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+    if (!REPLY_KEYS.has(key) || !v || typeof v !== "object") {
+      out[key] = v;
+      continue;
+    }
+    out[key] = Array.isArray(v)
+      ? v.map((row) => unmarshall(row as Record<string, any>))
+      : unmarshall(v as Record<string, any>);
+  }
+  return out;
+}

package/vendor/base/src/manifests/runtime/auth/oauth.ts

@@ -0,0 +1,76 @@
+/**
+ * OAUTH2 CLIENT CREDENTIALS. An auth scheme, so it is written once here rather than in
+ * every node that needs it (DECLARATIVE_NODES.md §2).
+ *
+ * Unlike a bearer key, this is not a value the manifest can template: the credential is a
+ * client id and secret that must be EXCHANGED for a short-lived token, over a form-encoded
+ * POST, and the result cached until it expires. That is computation over the request, and
+ * a manifest that tried to express it would need a request before its request.
+ *
+ * The token response is put back into scope as `token`, because some vendors return where
+ * to talk as well as how. Salesforce returns `instance_url` and the org's API lives there,
+ * not at the login host you authenticated against.
+ */
+
+interface Minted {
+  accessToken: string;
+  instanceUrl?: string;
+  expiresAt: number;
+}
+
+/**
+ * Cached per connected-app identity, not per node or per run.
+ *
+ * A workflow that makes six calls must not mint six tokens, and a vendor will rate-limit or
+ * refuse if it does. Keyed by client id AND token url so two orgs never share an entry.
+ */
+const CACHE = new Map<string, Minted>();
+
+/** Default life. Salesforce client-credentials sessions are ~2h; refresh well before. */
+const DEFAULT_TTL_MS = 110 * 60 * 1000;
+
+/** Drop a cached token, so the next call mints a fresh one. */
+export function invalidateToken(tokenUrl: string, clientId: string): void {
+  CACHE.delete(`${clientId}@${tokenUrl}`);
+}
+
+export async function mintClientCredentials(
+  tokenUrl: string,
+  clientId: string,
+  clientSecret: string,
+  scope: string | undefined,
+  force = false,
+): Promise<Minted> {
+  const key = `${clientId}@${tokenUrl}`;
+  const hit = CACHE.get(key);
+  if (!force && hit && hit.expiresAt > Date.now()) return hit;
+
+  // FORM ENCODED, not JSON. The OAuth2 spec says so and vendors enforce it, which is why
+  // this cannot ride the ordinary body path: that one always sends JSON.
+  const form = new URLSearchParams({ grant_type: "client_credentials", client_id: clientId, client_secret: clientSecret });
+  if (scope) form.set("scope", scope);
+
+  const res = await fetch(tokenUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: form.toString(),
+  });
+
+  const data: any = await res.json().catch(() => null);
+  if (!res.ok || !data?.access_token) {
+    // The description, not just the status: "invalid_client" tells you which of the two
+    // secrets is wrong, and a bare 400 does not.
+    const detail = data?.error_description ?? data?.error ?? res.statusText;
+    throw new Error(`oauth2ClientCredentials: token request to ${tokenUrl} failed (${res.status}): ${detail}`);
+  }
+
+  const minted: Minted = {
+    accessToken: data.access_token,
+    instanceUrl: typeof data.instance_url === "string" ? data.instance_url.replace(/\/+$/, "") : undefined,
+    // Honour the vendor's own expiry when it sends one, minus a minute of slack so a token
+    // cannot expire in flight.
+    expiresAt: Date.now() + (Number(data.expires_in) ? Number(data.expires_in) * 1000 - 60_000 : DEFAULT_TTL_MS),
+  };
+  CACHE.set(key, minted);
+  return minted;
+}

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

@@ -0,0 +1,159 @@
+/**
+ * WHO MAY RUN THIS NODE, enforced at node start (DECLARATIVE_NODES.md §9.13).
+ *
+ * The inbound question, about the CALLER. A call's `credential` is the outbound one: how the
+ * node proves itself to a vendor. Both were spelled `auth` until 2026-07-28, which is the
+ * reason the two were so easy to mistake for each other.
+ *
+ * WHY THIS FILE EXISTS. `requires.role` was in the node schema and checked by lint from the
+ * day the format shipped, and read by no runtime code at all: `compose.ts` never carried the
+ * field onto the composed node, so the executor could not have enforced it even if someone
+ * had written the check. Every doc said "schema + lint exist, the executor check does not".
+ * A security field that lints clean and does nothing is worse than no field, because a
+ * reviewer reads it as a decision that was made and is holding.
+ *
+ * WHAT THIS IS NOT. This does not admit anyone. The platform gate at the edge decides who
+ * gets in at all (default-deny JWT, `auth/publicEntry.ts` for the anonymous case). By the
+ * time a node runs the caller is already whoever they are going to be, and this only ever
+ * NARROWS: a node may demand more than the trigger did and can never waive what it demanded.
+ *
+ * FAILS LOUDLY, and that is a deliberate choice over the alternative. A node that no-ops on
+ * missing identity looks fine in testing and silently does nothing in production, and nobody
+ * finds out for a week. Throwing names the claim that was missing, in the run's error, on
+ * the node that wanted it.
+ */
+
+import { grantedTo } from "../../security/permissions.js";
+
+/** What the platform gate put on the run. Guests carry an id and nothing else. */
+interface Caller {
+  id?: string;
+  sub?: string;
+  email?: string;
+  roles?: string[];
+  permissions?: string[];
+}
+
+export class NodeAuthorizationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NodeAuthorizationError";
+  }
+}
+
+/**
+ * A guest is an ADMITTED anonymous visitor, not an absent one, and the two must not be
+ * conflated: a guest legitimately reached a public workflow, while `undefined` means no
+ * identity travelled at all. Both fail `required: true`, but only the first is expected.
+ *
+ * The id shape is the gate's contract (`publicEntry.ts` mints `guest:<uuid>` and refuses a
+ * session claiming any other shape), and the retired `guest-` spelling still counts because
+ * clients mint and keep these across sessions.
+ */
+function isGuest(user: Caller | undefined): boolean {
+  const id = String(user?.id ?? user?.sub ?? "");
+  return id.startsWith("guest:") || id.startsWith("guest-");
+}
+
+/**
+ * Roles and permissions are ONE namespace here, deliberately. Both are `noun:verb` claims
+ * parsed off the same token (`auth.ts` reads each from its own claim, Auth0-namespaced or
+ * not), and `marketplace:publish` is already checked as a permission while reading exactly
+ * like a role. Making an author know which claim their identity provider happened to put a
+ * string in would be a footgun with no upside: the question is whether the caller carries
+ * the claim, not which list it arrived in.
+ */
+/**
+ * Does this caller carry the claim a node asked for?
+ *
+ * THREE PLACES TO LOOK, AND THE THIRD IS THE ONE THAT WAS MISSING. Raw `roles` and raw
+ * `permissions` are a deployment's own vocabulary: a builder naming `finance:approve` means
+ * the exact claim their identity provider mints, which the platform neither knows nor should
+ * invent. That part is unchanged.
+ *
+ * What is added is the PLATFORM's grant map (security/permissions.ts). Without it one string
+ * meant two things in two places: a ROUTE requiring `credentials:manage` admitted an admin,
+ * while a NODE requiring `credentials:manage` refused the same person, because that
+ * permission is granted by their role rather than stamped on their token. Same question,
+ * same answer, wherever it is asked.
+ *
+ * It widens only for permissions the platform itself defines, and only for holders of a role
+ * that already grants them elsewhere. A deployment-specific claim must still be on the token.
+ */
+function carries(user: Caller | undefined, role: string): boolean {
+  if ([...(user?.roles ?? []), ...(user?.permissions ?? [])].includes(role)) return true;
+  return (grantedTo(user) as Set<string>).has(role);
+}
+
+/**
+ * TWO SOURCES, AND THE STRICTER WINS.
+ *
+ * The manifest's `auth` is the node AUTHOR's floor: "this node is inherently privileged",
+ * true of every copy of it everywhere. The instance's `authRequired` / `authRole` are the
+ * WORKFLOW BUILDER's, set per box on the canvas, because only they know that this
+ * particular box faces customers rather than staff.
+ *
+ * A role in particular has to be able to come from the instance. `finance:approve` is a
+ * claim ONE deployment's identity provider mints, so a node published to the marketplace
+ * cannot name it: the author does not know the role vocabulary of the universes that
+ * install their node, and the builder does.
+ *
+ * Neither source can loosen the other. Requirements only narrow, which is the same law the
+ * trigger's public toggle obeys, so both roles are demanded when both exist rather than one
+ * overriding the other.
+ */
+function combine(
+  manifest: { required: boolean; role?: string },
+  config: any,
+): { required: boolean; roles: string[] } {
+  // Read STRAIGHT off the instance config and never through the template resolver. A gate
+  // that resolved `{{ ... }}` would let the thing being gated choose its own answer.
+  const instanceRequired = config?.authRequired === true;
+  const instanceRole = typeof config?.authRole === "string" && config.authRole.trim() ? config.authRole.trim() : undefined;
+
+  const roles = [manifest.role, instanceRole].filter((r): r is string => !!r);
+  // A role implies a signed-in caller wherever it came from, so an instance role that
+  // someone set while leaving the toggle off still demands identity rather than being
+  // quietly ignored.
+  return { required: manifest.required || instanceRequired || roles.length > 0, roles };
+}
+
+/**
+ * Throws unless this caller may run this node. Called once per node start, before any call
+ * is made, so a refused run costs no vendor request and no side effect.
+ *
+ * `nodeAuth` in compose.ts has already collapsed the unsatisfiable `role` + `required: false`
+ * pair in the manifest, so a manifest role always implies `required: true`.
+ */
+export function assertAuthorized(
+  node: { type: string; auth?: { required: boolean; role?: string } },
+  executionContext: any,
+  config?: any,
+): void {
+  // Absent means a manifest composed before this field existed. Treated as "signed in
+  // required" for the same reason compose.ts does: the safe reading of a node that never
+  // said, rather than the convenient one.
+  const want = combine(node.auth ?? { required: true }, config);
+  if (!want.required) return;
+
+  const user: Caller | undefined = executionContext?.auth?.user;
+  const identified = !!(user?.id ?? user?.sub) && !isGuest(user);
+
+  if (!identified)
+    throw new NodeAuthorizationError(
+      `${node.type} requires a signed-in caller${want.roles.length ? ` carrying ${want.roles.map((r) => `"${r}"`).join(" and ")}` : ""}, and this run has ` +
+        (isGuest(user) ? "an anonymous guest" : "no identity") +
+        `. The workflow's trigger admitted the run; this step asks for more than the trigger did, ` +
+        `set either on the node itself (node.yaml auth) or on this box in the workflow (Require sign-in).`,
+    );
+
+  // NAMES THE CLAIM. A bare "forbidden" sends whoever hit it to read the manifest to find
+  // out what they lacked, and an operator granting it needs the exact string anyway.
+  const missing = want.roles.filter((r) => !carries(user, r));
+  if (missing.length)
+    throw new NodeAuthorizationError(
+      `${node.type} requires the role${missing.length > 1 ? "s" : ""} ${missing.map((r) => `"${r}"`).join(" and ")}, ` +
+        `which this caller does not carry. ` +
+        `Present claims: ${[...(user?.roles ?? []), ...(user?.permissions ?? [])].join(", ") || "none"}.`,
+    );
+}

package/vendor/base/src/manifests/runtime/channels/final.ts

@@ -0,0 +1,171 @@
+/**
+ * THE LAST CALL — the one whose reply becomes the node's answer.
+ *
+ * Separate from `runCalls` because it is the only call that may STREAM. Every earlier call
+ * settles and exists so a later one can read it; this one is framed onto the output connectors,
+ * so it is the single place that has to know about every shape a reply can take: a settled body,
+ * an SSE stream, a duplex session, a walked pagination, a polled job, a chunked write, a state
+ * write, a loop step. A node that makes one call is just this, with nothing before it.
+ *
+ * ONE DISPATCH, in this order, and the order matters in one place: `transport: ws` is tested
+ * BEFORE `sendRequest`, because a socket handshake is not an HTTP request and issuing one would
+ * open a second connection to the vendor and pay for it.
+ *
+ * `base` is the emitter's shared scope, and every branch records its reply into it under the
+ * call's own name BEFORE any row fires. Without that, `calls.<name>` held the earlier calls only
+ * and the last one was reachable as `response` alone. That asymmetry was silent and it bit
+ * immediately: a service method and a graph run sharing ONE $ref'd expression behaved
+ * differently, because the service channel puts every call through `runCalls` and had the name
+ * while the graph run did not. An expression written once must mean one thing.
+ */
+import type { ComposedNode } from "../../compose.js";
+import type { RunContext } from "../context.js";
+import { evaluate, render } from "../templating.js";
+import { sendRequest, buildRequest, performPresign } from "../http/request.js";
+import { readSse, readSettled, assertOk } from "../http/response.js";
+import { runDuplexSession } from "../duplex/session.js";
+import type { AudioLane } from "../duplex/audioLane.js";
+import { performState, type StateStore } from "../state.js";
+import { fetchPaginated } from "../loops/paginate.js";
+import { fetchPolled } from "../loops/poll.js";
+import { sendChunked } from "../loops/chunk.js";
+import { performLoop } from "../loops/loop.js";
+import { performDoc } from "../docstore/index.js";
+import type { Emitter } from "../events.js";
+import type { ToolBridge } from "../tools/toolloop.js";
+import { makeUsageCollector } from "../usage.js";
+
+export async function runFinal(
+  node: ComposedNode,
+  call: any,
+  ctx: RunContext,
+  emitter: Emitter,
+  base: Record<string, unknown>,
+  store?: StateStore,
+  lane?: AudioLane | null,
+  tools?: ToolBridge,
+): Promise<number> {
+  /** Every branch settles the same way: name the reply, then let the events table shape it. */
+  const settle = async (payload: unknown): Promise<number> => {
+    (base.calls as Record<string, unknown>)[call.name] = payload;
+    await emitter.response(payload);
+    return 200;
+  };
+
+  // A DOCSTORE op as the last (often only) call — SmartDocument's whole workflow channel is
+  // one `docstore: render`. Same defaulting as the runCalls branch: arguments are the
+  // caller's params unless the call names its own, and the doc's key derives from the run's
+  // ids inside performDoc.
+  if (call.docstore) {
+    const args = call.params
+      ? ((await evaluate(call.params, ctx as unknown as Record<string, unknown>)) as Record<string, any>)
+      : ctx.params;
+    return settle(await performDoc(String(call.docstore), args ?? {}, store?.raw, ctx.scope, ctx.config));
+  }
+
+  // A node whose LAST act is a state write settles on that write, so the events table can
+  // emit what was stored.
+  if (call.state) {
+    const value = call.value ? await evaluate(call.value, ctx as unknown as Record<string, unknown>) : undefined;
+    return settle(await performState(call.state, String(render(call.key, ctx)), value, call.max, store, ctx.scope));
+  }
+
+  // A LOOP step. LoopStart settles on the pass it opened or read, LoopEnd on the step it
+  // advanced, and each one's events table shapes its connectors from that single payload.
+  if (call.loop) {
+    const value = call.value ? await evaluate(call.value, ctx as unknown as Record<string, unknown>) : undefined;
+    return settle(await performLoop(call.loop, ctx.scope?.executionId, String(render(call.key, ctx)), value, store?.loop));
+  }
+
+  // Presign: no request at all — the node settles on the minted urls, always a list.
+  // S3Files ends on one when links are asked for: list, then mint a link per object found.
+  if (call.presign) return settle(await performPresign(node, call, ctx));
+
+  // Chunked: many requests over one collection, one summary reply.
+  if (call.chunk) return settle(await sendChunked(node, call, ctx, node.type));
+
+  // Paginated: many requests, one accumulated reply, so the events table sees the whole set.
+  if (call.paginate) return settle(await fetchPaginated(node, call, ctx, node.type));
+
+  // Polled: a job, started and waited on, settling as the final status payload.
+  if (call.poll) return settle(await fetchPolled(node, call, ctx, node.type));
+
+  // DUPLEX, and it must come BEFORE sendRequest, because a socket handshake is not an HTTP
+  // request and issuing one would open a second connection to the vendor and pay for it.
+  //
+  // `buildRequest` is reused only to RESOLVE the url and the credential headers: a ws
+  // handshake carries the credential in a header exactly as a request does, so the schemes
+  // and the template resolution should be the same code rather than a second implementation
+  // that drifts. Its body and method are discarded, because a session has neither.
+  if (call.transport === "ws") {
+    const built = await buildRequest({ request: call }, ctx);
+    const headers = Object.fromEntries(
+      Object.entries((built.init.headers ?? {}) as Record<string, string>).filter(([k]) => k.toLowerCase() !== "content-type"),
+    );
+    // The audio lane keys everything by conversation, and the events already carry it. Falls
+    // back to the execution id so a node with no conversation still holds a valid session and
+    // still emits transcripts — it simply has nowhere to send audio.
+    const conversationId = String(
+      (ctx as any).scope?.conversationId ?? (ctx as any).config?.conversationId ?? (ctx as any).scope?.executionId ?? node.type,
+    );
+    // Every other transport builds one of these; the socket built none, so voice calls reported
+    // no tokens at all. `usage.save()` sits BEFORE the throw: a call that ended badly still
+    // burned what it spoke.
+    const usage = makeUsageCollector(node, ctx);
+    const result = await runDuplexSession({
+      node,
+      call,
+      ctx,
+      emitter,
+      url: built.url,
+      headers,
+      lane: lane ?? null,
+      conversationId,
+      tools,
+      usage,
+      onError: (message) => {
+        // Surfaced rather than thrown: one bad frame mid-call must not end a conversation the
+        // person is still having.
+        void emitter.narrator(message);
+      },
+    });
+    usage.save();
+    if (result.reason === "error") throw new Error(`${node.type}: duplex session failed: ${result.error}`);
+    return 200;
+  }
+
+  const res = await sendRequest(node, call, ctx, node.type);
+  const transport = call.transport;
+
+  if (transport === "json" || transport === "text") {
+    const payload = await readSettled(res, transport, call.encoding);
+    await assertOk(node, call, payload, node.type);
+    // Token usage: a settled vendor body carries it inline (Chat Completions puts it
+    // top-level). One payload, so see + save in one breath.
+    const usage = makeUsageCollector(node, ctx);
+    usage.see(payload);
+    usage.save();
+    // Named BEFORE emitting, so a row reading calls.<name> sees it.
+    //
+    // Settling only. A streaming call has no single reply to name: it is a sequence, and
+    // each event arrives as `response`. Inventing a value for `calls.<name>` there would be
+    // a guess about which event counted.
+    (base.calls as Record<string, unknown>)[call.name] = payload;
+    // No `match`: a settled body is one event, so every `from: response` row fires over it.
+    await emitter.response(payload);
+    return res.status;
+  }
+
+  if (transport === "sse") {
+    const usage = makeUsageCollector(node, ctx);
+    await readSse(res, call.terminator, async (payload) => {
+      await assertOk(node, call, payload, node.type);
+      usage.see(payload);
+      await emitter.response(payload, payload.type);
+    });
+    usage.save();
+    return res.status;
+  }
+
+  throw new Error(`transport "${transport}" is declared in the schema but not implemented in the executor`);
+}