@unoverse-platform/studio 0.1.89 → 0.1.91

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

@@ -0,0 +1,223 @@
+/**
+ * `api.events` — everything that leaves a node, in one ordered table.
+ *
+ * ONE ROW PER OUTPUT CONNECTOR, in the same order the connectors are declared, so reading
+ * the table tells you the node's entire outward behaviour without opening another file.
+ * Lint enforces both the coverage and the order.
+ *
+ * This replaced four separate mechanisms (`response.events`, `response.finalize`,
+ * `response.map`, and `narrate.output`), which between them meant a five-output node
+ * declared its outputs in four places under three different key names. That is also how
+ * a real bug got in: the tool RESULT is produced by our tool loop and never appears in
+ * the HTTP stream, but `response.events` was the only list available, so it was wired to
+ * the nearest wrong thing (the tool CALL, fired before the tool had even run).
+ *
+ * A row says WHERE it fires from:
+ *
+ *   from: response   streaming: each event whose type equals `match`
+ *                    settling:  once, over the whole body
+ *   from: narrator   each line the narrator produces
+ *   from: tool       after each tool call returns, with its result
+ *   from: complete   once, at the end, over everything emitted
+ *
+ * The executor owns what data cannot express: accumulating, throttling, and flushing what
+ * throttling held back. `accumulate` and the two throttles exist because a delta-per-event
+ * stream is not what a consumer wants. It wants the text so far, at a readable rate.
+ */
+import type { ComposedNode } from "../compose.js";
+import { evaluate, render } from "./templating.js";
+import type { Emission } from "./http/response.js";
+
+export type EventSource = "response" | "narrator" | "tool" | "complete";
+
+/** Per-row state. Throttling and accumulation are stateful across a run, so rows own it. */
+interface RowState {
+  /** Running total, for `accumulate: true`. */
+  acc: string;
+  /** Held back by a throttle and not yet emitted. */
+  pending?: unknown;
+  /** Characters added since the last emission, for `throttleChars`. */
+  chars: number;
+  /** When we last emitted, for `throttleMs`. */
+  lastAt: number;
+  /** Resolved `send` target held alongside `pending`: it is known at fire time, not at flush. */
+  to?: string;
+}
+
+/**
+ * The emitter for ONE run. Holds every emission it made, because `from: complete` is
+ * defined over them and because a node's settled outputs are the last value per connector.
+ */
+export function makeEmitter(node: ComposedNode, onEmit: (e: Emission) => void, base: Record<string, unknown> = {}) {
+  const rows: any[] = node.api?.events ?? [];
+  const state = new Map<number, RowState>();
+  const emissions: Emission[] = [];
+
+  const stateFor = (i: number) => {
+    let s = state.get(i);
+    if (!s) state.set(i, (s = { acc: "", chars: 0, lastAt: 0 }));
+    return s;
+  };
+
+  /**
+   * The row's destination. `emit` names an output CONNECTOR; `send` names another NODE.
+   *
+   * A send row is how one node hands something to a named node without a wire: the loop-back
+   * is the first case (LoopEnd already names its partner in `loopStartNodeId`, so an edge would
+   * be the same fact stated twice), and it is deliberately not loop-specific.
+   */
+  const destination = (row: any, to?: string) =>
+    row.send ? { to, handle: row.handle ?? "input" } : { emit: row.emit };
+
+  /** Apply accumulate + throttle, then emit or hold. */
+  const deliver = (row: any, i: number, raw: unknown, to?: string) => {
+    if (raw === undefined || raw === null) return;
+    const s = stateFor(i);
+
+    let value = raw;
+    if (row.accumulate) {
+      s.acc += String(raw);
+      value = s.acc;
+    }
+
+    // Throttled: remember the newest value and let a later tick or the flush send it.
+    // Never DROP it, or the last words of an answer go missing.
+    if (row.throttleMs) {
+      const now = Date.now();
+      if (now - s.lastAt < row.throttleMs) {
+        s.pending = value;
+        s.to = to;
+        return;
+      }
+      s.lastAt = now;
+    }
+    if (row.throttleChars) {
+      s.chars += String(raw).length;
+      if (s.chars < row.throttleChars) {
+        s.pending = value;
+        s.to = to;
+        return;
+      }
+      s.chars = 0;
+    }
+
+    s.pending = undefined;
+    const emission = { ...destination(row, to), value };
+    emissions.push(emission);
+    onEmit(emission);
+  };
+
+  /**
+   * END OF A TURN: flush what the throttle holds, then start the accumulator over.
+   *
+   * `accumulate` runs for the length of a RUN, which is one answer over HTTP and a whole
+   * CONVERSATION over a socket — so without this every turn carries every turn before it.
+   * Flush BEFORE clearing, or the turn's closing words go with it.
+   */
+  const resetTurn = (match?: string) => {
+    if (match === undefined) return;
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      if (!row.resetOn) continue;
+      const hit = Array.isArray(row.resetOn) ? row.resetOn.includes(match) : row.resetOn === match;
+      if (!hit) continue;
+      const s = state.get(i);
+      if (!s) continue;
+      if (s.pending !== undefined) {
+        const emission = { emit: row.emit, value: s.pending };
+        s.pending = undefined;
+        emissions.push(emission);
+        onEmit(emission);
+      }
+      s.acc = "";
+      s.chars = 0;
+      s.lastAt = 0;
+    }
+  };
+
+  // `base` is what every row sees regardless of where it fired: config, the signed-in
+  // user, and (for a chained call) each step's reply. A row's own source keys are layered
+  // on top, so `response` still means the thing that just arrived.
+  const fire = async (source: EventSource, sourceScope: Record<string, unknown>, match?: string) => {
+    const scope = { ...base, ...sourceScope };
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      if ((row.from ?? "response") !== source) continue;
+      // `match` applies to streaming rows only; a settling row has no event type to match.
+      // A row may name SEVERAL event types (a list) when one connector accumulates from
+      // more than one wire event — e.g. reasoning summary deltas plus the part-done
+      // marker that separates summary sections. The value expression reads
+      // `response.type` to tell them apart.
+      if (match !== undefined && row.match !== undefined) {
+        const hit = Array.isArray(row.match) ? row.match.includes(match) : row.match === match;
+        if (!hit) continue;
+      }
+      if (row.when && !(await evaluate(row.when, scope))) continue;
+      // A send row's target is a TEMPLATE over the same scope (`{{ config.loopStartNodeId }}`),
+      // rendered here rather than in deliver() because only the fire has the scope. Empty means
+      // the author's config field is unset: fail loudly, exactly as a missing loop state does,
+      // rather than dropping the message and leaving a loop that silently stops after one pass.
+      let to: string | undefined;
+      if (row.send) {
+        to = String(render(row.send, scope as any) ?? "").trim();
+        if (!to) {
+          throw new Error(
+            `${node.type}: events row ${i} sends to "${row.send}", which resolved to nothing. ` +
+              `Set that config field to the target node's id.`,
+          );
+        }
+      }
+      deliver(row, i, await evaluate(row.value, scope), to);
+      // First match wins per event, which is what keeps a chatty API readable.
+      if (match !== undefined) break;
+    }
+  };
+
+  return {
+    emissions,
+
+    /**
+     * One streamed event, or one settled body when `match` is undefined.
+     *
+     * `extra` carries the replies of earlier calls, which only the caller that ran them
+     * knows about.
+     */
+    response: async (payload: any, match?: string, extra: Record<string, unknown> = {}) => {
+      await fire("response", { ...extra, response: payload }, match);
+      // AFTER the rows have seen it. A turn-ending event may itself be something a row emits
+      // on, and resetting first would clear the accumulator the row is about to read.
+      resetTurn(match);
+    },
+    narrator: (line: string) => fire("narrator", { narrator: { line } }),
+    tool: (call: { name: string; args: unknown; output: unknown }) => fire("tool", { call }),
+
+    /**
+     * Send anything a throttle held back, then run the `complete` rows over the whole run.
+     * Flushing first matters: `complete` is usually defined over what was emitted.
+     */
+    async finish() {
+      for (let i = 0; i < rows.length; i++) {
+        const s = state.get(i);
+        if (s?.pending === undefined) continue;
+        const emission = { ...destination(rows[i], s.to), value: s.pending };
+        s.pending = undefined;
+        emissions.push(emission);
+        onEmit(emission);
+      }
+      await fire("complete", { events: emissions.slice() });
+      return emissions;
+    },
+
+    /** A node's settled outputs are the LAST value seen on each connector. */
+    outputs(): Record<string, unknown> {
+      const out: Record<string, unknown> = {};
+      // A send row addresses a node, not a connector, so it is NOT one of this node's outputs.
+      // Including it would put a phantom handle in __outputs, and the engine's routing decides
+      // which edges fire from exactly that set.
+      for (const e of emissions) if (e.emit) out[e.emit] = e.value;
+      return out;
+    },
+  };
+}
+
+export type Emitter = ReturnType<typeof makeEmitter>;

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

@@ -0,0 +1,53 @@
+/**
+ * NAMED HELPERS, bound for the duration of one run.
+ *
+ * A package declares functions under `helpers:` in any shared/ file; every expression in
+ * every node of that package can then call them by name. What this module solves is getting
+ * the bag into scope: `evaluate` is called from 50-odd places, each building its own small
+ * scope object ({ response }, { call }, { tool }, ...), and adding a `helpers` key to every
+ * one of them would guarantee that someone adds the fifty-first without it. A helper that
+ * works in `returns` and not in an events row is worse than no helpers at all.
+ *
+ * AsyncLocalStorage instead, bound once where a run begins. It is the platform primitive for
+ * exactly this and it is concurrency-safe: two nodes running at once each see their own bag,
+ * which a module-level "current package" variable would not give.
+ *
+ * NOT bound means an expression naming `helpers` fails with `unknown identifier 'helpers'`
+ * from the sandbox — loud, and pointing at the expression. There is deliberately no empty-bag
+ * fallback: a helper call that silently returned undefined would be the same class of quiet
+ * wrong answer as the shallow $ref merge.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { makeHelpers } from "../../template/SafeExpression.js";
+import type { ComposedNode } from "../compose.js";
+
+type Bag = Record<string, (...a: unknown[]) => unknown>;
+
+const STORE = new AsyncLocalStorage<Bag>();
+
+/**
+ * Built ONCE per composed node and cached against it.
+ *
+ * Each helper parses its body eagerly, so rebuilding the bag on every call would re-parse
+ * every helper on every request. Keyed by the composed node object, which the loader
+ * replaces wholesale when a package reloads, so a stale bag cannot outlive its source.
+ */
+const CACHE = new WeakMap<ComposedNode, Bag>();
+
+function bagFor(node: ComposedNode): Bag {
+  const hit = CACHE.get(node);
+  if (hit) return hit;
+  const built = makeHelpers(node.helpers ?? {});
+  CACHE.set(node, built);
+  return built;
+}
+
+/** Run `fn` with this node's helpers in scope for every expression it evaluates. */
+export function withHelpers<T>(node: ComposedNode, fn: () => Promise<T>): Promise<T> {
+  return STORE.run(bagFor(node), fn);
+}
+
+/** The bag bound to the current run, or undefined outside one. */
+export function currentHelpers(): Bag | undefined {
+  return STORE.getStore();
+}

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

@@ -0,0 +1,118 @@
+/**
+ * THE ALLOWED_HOSTS BOUNDARY. Its own file because it is the security control.
+ *
+ * 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.
+ */
+/**
+ * THE ALLOWED_HOSTS BOUNDARY.
+ *
+ * A manifest cannot execute code, but it can say "send this credential to
+ * evil.example", and that is exfiltration with no code at all. SECURITY.md bounds a
+ * code node by PROVENANCE (the first-party npm scope) and a template expression by
+ * having no credentials in scope. A manifest node is neither: it arrives as data yet
+ * holds a credential and a URL. This is its boundary.
+ *
+ * Deny by default. A package that declares no `allowedHosts` reaches nothing.
+ */
+export function assertAllowedHost(
+  url: string,
+  allowedHosts: string[],
+  nodeType: string,
+  /**
+   * Does THIS call send a credential? Only a call that does is bounded by the host list in
+   * the strict sense; see the `"*"` rule below.
+   */
+  carriesCredential = true,
+): void {
+  // BOTH forms: `host` carries the port, `hostname` never does. A pattern cannot express a
+  // port (the schema forbids the colon), so the match below accepts either.
+  let host: string;
+  let hostname: string;
+  try {
+    const parsed = new URL(url);
+    // `wss:` is https for sockets: TLS from the first byte, and the handshake IS an https
+    // request that then upgrades. A duplex node carries its bearer token on that handshake, so
+    // this must accept wss and must keep refusing plain `ws:`, which would put the credential
+    // on the wire in clear text exactly as `http:` would.
+    const secure = parsed.protocol === "https:" || parsed.protocol === "wss:";
+    if (!secure && parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1")
+      throw new Error(`${nodeType}: refusing a non-https request to ${parsed.protocol}//${parsed.host} — a credential must not travel in clear text`);
+    host = parsed.host.toLowerCase();
+    hostname = parsed.hostname.toLowerCase();
+  } catch (err: any) {
+    if (err?.message?.startsWith(nodeType)) throw err;
+    throw new Error(`${nodeType}: request url is not a valid URL: ${url}`);
+  }
+
+  const allowed = allowedHosts.some((pattern) => {
+    /**
+     * `"*"` — ANY HOST, and ONLY for a call that sends no credential.
+     *
+     * Some nodes legitimately fetch a url a person supplies: an image for a model to look
+     * at, a document to read. That url cannot be declared in advance, because the whole
+     * point is that it is not known until someone types it.
+     *
+     * Allowing it is safe HERE and nowhere else, because of what this boundary is actually
+     * for. SECURITY.md's concern is exfiltration: a manifest saying "POST this credential to
+     * evil.example". A call with no `auth` block has no credential to leak — it is an
+     * ordinary unauthenticated GET, the same thing any browser does.
+     *
+     * Two things still bound it. Non-https is already refused above, which puts the cloud
+     * metadata endpoint and plaintext internal services out of reach. And the moment a call
+     * carries a credential, `"*"` stops matching and the real host list applies — so a
+     * tampered manifest cannot move the credential onto the wildcard call.
+     */
+    if (pattern === "*") return !carriesCredential;
+    /**
+     * `**.a.com` — ANY DEPTH. Written with two stars because it is a deliberately weaker
+     * claim than one, and the author should have to say so.
+     *
+     * AWS forced this. Its endpoints are inherently multi-level: `dynamodb.us-east-1.
+     * amazonaws.com` is two labels deep and an S3 bucket is three
+     * (`bucket.s3.region.amazonaws.com`), because both the region AND the bucket are part
+     * of the name. A single-level wildcard cannot express that, and the alternatives were
+     * worse: listing every region defeats itself the day AWS adds one, and a bucket name is
+     * config, so it cannot be listed at all.
+     *
+     * Still bounded, and that is the point: `**.amazonaws.com` reaches any AWS host and
+     * NOTHING else, so a tampered manifest still cannot post a credential to evil.example.
+     */
+    if (pattern.startsWith("**.")) {
+      const suffix = pattern.slice(2); // ".amazonaws.com"
+      // A non-empty label must precede it, so `**.a.com` does not match a bare `a.com`.
+      return host.endsWith(suffix) && host.length > suffix.length;
+    }
+    if (pattern.startsWith("*.")) {
+      const suffix = pattern.slice(1); // ".example.com"
+      // One level only: *.a.com matches x.a.com, not x.y.a.com.
+      return host.endsWith(suffix) && !host.slice(0, -suffix.length).includes(".");
+    }
+    /**
+     * EXACT, and a pattern with no port matches ANY port on that host.
+     *
+     * `parsed.host` carries the port when it is not the scheme's default, while
+     * package.schema.json's allowedHosts pattern forbids a colon outright — so a port can
+     * never be written down. Comparing the two strings therefore made every non-default
+     * port UNREACHABLE, with an error naming a host that looked identical to the declared
+     * one: `refusing a request to "127.0.0.1:4106". This package allows "127.0.0.1"`.
+     *
+     * It stayed hidden because vendors are on https/443, where `host` has no port. The
+     * first caller to hit it was a node calling the PLATFORM, which listens on 4106.
+     *
+     * Nothing is weakened: a port could not be expressed in a pattern, so this restricts
+     * exactly what it always restricted, the host. The non-https rule above is unchanged
+     * and still bounds what a plaintext call can reach.
+     */
+    return host === pattern || hostname === pattern;
+  });
+
+  if (!allowed)
+    throw new Error(
+      `${nodeType}: refusing a request to "${host}". This package allows ${allowedHosts.length ? allowedHosts.map((h) => `"${h}"`).join(", ") : "NOTHING"}. ` +
+        `A manifest may only call hosts its package declared in package.yaml, so a pasted node cannot ship your credentials somewhere you never approved.` +
+        (allowedHosts.includes("*") && carriesCredential
+          ? ` This package does declare "*", but that covers unauthenticated calls only, and THIS call sends a credential.`
+          : ""),
+    );
+}