@unoverse-platform/studio 0.1.90 → 0.1.91

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

@@ -0,0 +1,125 @@
+/**
+ * THE SERVICE CHANNEL: a method this node offers over a service edge, exposed as MCP.
+ *
+ * The other of the two ways a node is reached, and they never cross (08-mcp-services.md).
+ * Called ad-hoc by an agent rather than run by the graph, and it hands back ONE value rather
+ * than emitting on output connectors — which is why the manifest says `returns` and why no
+ * events row is involved anywhere in here.
+ */
+import type { ComposedNode } from "../../compose.js";
+import type { RunContext } from "../context.js";
+import { evaluate } from "../templating.js";
+import { runCalls } from "../http/request.js";
+import type { StateStore } from "../state.js";
+import { rowComponentsFromResults, renderRowComponents } from "../../../agent-mcp/rowComponents.js";
+import { withHelpers } from "../helpers.js";
+
+/**
+ * THE CALLER'S LIVE SESSION, supplied by the EXECUTOR and never by the manifest.
+ *
+ * `accessToken` is the deliberate omission from RunContext (§9.4): a manifest is data that
+ * can arrive by paste or database row, and one that could read the token could forward it to
+ * any host its allowedHosts allows. It is threaded here instead, the same way the tool bridge
+ * already uses it — the platform calling its own surface on the user's behalf, rather than
+ * data deciding where a secret goes.
+ */
+export interface CallerSession {
+  userId?: string;
+  conversationId?: string;
+  chatId?: string;
+  accessToken?: string;
+}
+
+/**
+ * The package's named helpers are bound around the WHOLE method, not around `returns` alone:
+ * a call's `when`, a url, an error message and the projection are all expressions, and a
+ * helper that some of them could call and others could not would be a rule with no reason
+ * behind it.
+ */
+export async function performService(
+  node: ComposedNode,
+  method: string,
+  params: Record<string, any>,
+  ctx: RunContext,
+  store?: StateStore,
+  session?: CallerSession,
+): Promise<unknown> {
+  return withHelpers(node, () => serviceMethod(node, method, params, ctx, store, session));
+}
+
+async function serviceMethod(
+  node: ComposedNode,
+  method: string,
+  params: Record<string, any>,
+  ctx: RunContext,
+  store?: StateStore,
+  session?: CallerSession,
+): Promise<unknown> {
+  const spec = node.api?.service?.[method];
+  if (!spec) {
+    const known = Object.keys(node.api?.service ?? {});
+    throw new Error(
+      `${node.type} has no service method "${method}"${known.length ? ` — it has ${known.join(", ")}` : " — it has none"}`,
+    );
+  }
+
+  const scoped: RunContext = { ...ctx, params };
+
+  // Every call settles here, including the last: a method hands back ONE value, so there
+  // is no connector for a stream to emit onto.
+  const { results, last } = await runCalls(node, spec.calls, scoped, `${node.type}.${method}`, store);
+
+  /**
+   * CONTENT CARDS, rendered from the rows this method surfaced.
+   *
+   * BEFORE `returns`, and that ordering is the whole reason this lives here rather than in
+   * the executor: `returns` is where a node projects its reply down to what a model should
+   * read, and a render needs the FULL row (the component uri, the images, the authored copy)
+   * that the projection strips. Rendering after it would draw from data that no longer has
+   * what the component is made of.
+   *
+   * DATA-DRIVEN, never a model tool: a row that carries a component renders it the moment it
+   * surfaces, so the model cannot forget to show it, describe one that is not there, or
+   * decide not to bother. No prompt is involved anywhere.
+   *
+   * Fire-and-forget and deliberately not awaited: this is a side channel to a screen, and
+   * a slow render must not hold up the answer the caller is waiting on. With no live session
+   * (builder, tests, headless) `renderRowComponents` no-ops on the missing userId, so a
+   * manifest declaring this stays pure everywhere it is not wanted, with no flag to juggle.
+   */
+  if (spec.renderComponents) {
+    const rows = await evaluate(spec.renderComponents, { response: last, calls: results, params, config: ctx.config });
+    const found = rowComponentsFromResults(rows);
+    // SAY WHAT HAPPENED, always: this lane no-ops on no component rows or no live session,
+    // and silence must not read as success. `renderRowComponents` logs its own settles.
+    const sessionCtx = {
+      userId: session?.userId,
+      conversationId: session?.conversationId,
+      chatId: session?.chatId,
+      accessToken: session?.accessToken,
+    };
+    const log = (m: string) => console.log(`[manifests] ${node.type}: ${m}`);
+    if (found.length) {
+      if (!session?.userId) {
+        console.log(`[manifests] ${node.type}: ${found.length} row component(s) not rendered — no live session on this run`);
+      }
+      renderRowComponents(found, sessionCtx, log);
+    } else {
+      const n = Array.isArray(rows) ? rows.length : 0;
+      console.log(`[manifests] ${node.type}: no row components in ${n} row(s)`);
+      // The empty delivery is announced (§12e mechanical spent rule): this search
+      // ran and surfaced nothing, and the standing set's fate hangs on that fact.
+      renderRowComponents(found, sessionCtx, log);
+    }
+  }
+
+  // `params`, `config` and `user` are in scope so a method can shape its result from what
+  // it was asked for and who asked, not only from what came back.
+  return evaluate(spec.returns, {
+    response: last,
+    calls: results,
+    params,
+    config: ctx.config,
+    user: ctx.user,
+  });
+}

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

@@ -0,0 +1,310 @@
+/**
+ * THE WORKFLOW CHANNEL: what a node does when the GRAPH triggers it.
+ *
+ * One of the two ways a node is reached, and they never cross (08-mcp-services.md). This one
+ * fires the node's output connectors and answers nobody; `service.ts` answers a caller and
+ * fires no connectors.
+ *
+ * What lives here is the SHAPE OF A RUN and nothing else — which calls lead, which one settles
+ * the node, what an events row may see. The individual capabilities are elsewhere: `final.ts`
+ * dispatches the last call, `../http/request.ts` runs the leading ones, `../narrate.ts` talks
+ * while it works.
+ */
+import type { ComposedNode } from "../../compose.js";
+import type { RunContext } from "../context.js";
+import { evaluate } from "../templating.js";
+import { runCalls } from "../http/request.js";
+import type { Emission } from "../http/response.js";
+import type { AudioLane } from "../duplex/audioLane.js";
+import type { StateStore } from "../state.js";
+import { makeEmitter } from "../events.js";
+import { makeNarrator } from "../narrate.js";
+import { runToolLoop, type ToolBridge } from "../tools/toolloop.js";
+import { runFinal } from "./final.js";
+import { withHelpers } from "../helpers.js";
+import { clientTransport } from "../../../platform/clientTransport.js";
+import { rowComponentsFromResults, renderRowComponents } from "../../../agent-mcp/rowComponents.js";
+import type { CallerSession } from "./service.js";
+
+export interface RunResult {
+  outputs: Record<string, unknown>;
+  emissions: Emission[];
+  status: number;
+}
+
+/**
+ * `onEmit` receives every streamed emission as it happens, which is what a CallbackNode
+ * forwards to its output connectors in real time.
+ */
+export async function performApi(
+  node: ComposedNode,
+  ctx: RunContext,
+  onEmit: (e: Emission) => void = () => {},
+  tools?: ToolBridge,
+  store?: StateStore,
+  lane?: AudioLane | null,
+  session?: CallerSession,
+): Promise<RunResult> {
+  // The package's named helpers, bound for the whole run — see the same wrapper on the
+  // service channel. Every expression this run evaluates, in a call or an events row or a
+  // tool exchange, sees the same bag.
+  return withHelpers(node, () => runApi(node, ctx, onEmit, tools, store, lane, session));
+}
+
+async function runApi(
+  node: ComposedNode,
+  ctx: RunContext,
+  onEmit: (e: Emission) => void = () => {},
+  tools?: ToolBridge,
+  store?: StateStore,
+  lane?: AudioLane | null,
+  session?: CallerSession,
+): Promise<RunResult> {
+  const api = node.api;
+  if (!api) throw new Error(`Node "${node.type}" has no api block, so there is nothing to perform`);
+
+  /**
+   * A NODE MAY MAKE NO REQUEST AT ALL.
+   *
+   * Two different things used to fail on the same check, and only one of them should:
+   *
+   *   service-only   `service` methods and nothing else. The graph must NOT run it — it
+   *                  answers a caller over a service edge, and has no inputs to reach it by.
+   *                  Still refused, below.
+   *   events-only    an `events` table and no calls. LEGITIMATE. `IfElse` picks which output
+   *                  dot the data lands on; `Relay` passes its input through; `Note` does
+   *                  nothing at all. There is no url, so `run` would be a fiction.
+   *
+   * NOT AN ESCAPE HATCH, which is the only reason this is allowed (§2, §10). The safety
+   * property is that a manifest cannot EXECUTE — and an events-only node executes nothing. It
+   * is an events table over already-resolved config and the incoming signal, evaluated by the
+   * same sandbox as every other expression. Nothing new is reachable; there is simply no
+   * request in front of it.
+   *
+   * The distinction is `events`, not the absence of `run`, so a service-only node is still
+   * refused with the message it always had.
+   */
+  const eventsOnly = !api.run?.length && !!api.events?.length;
+  if (!api.run?.length && !eventsOnly)
+    throw new Error(`Node "${node.type}" has only service methods — the graph cannot run it`);
+
+  // LEAD then FINAL. Every call but the last settles and just fills `calls.<name>`; the
+  // last is the one whose reply becomes the node's answer, so it alone may stream. A node
+  // that makes one call is the ordinary case and takes this path with an empty lead.
+  const lead = eventsOnly ? [] : api.run.slice(0, -1);
+  const final = eventsOnly ? undefined : api.run[api.run.length - 1];
+
+  /**
+   * WHAT AN EVENTS ROW MAY SEE. Mutated rather than copied: `base` is spread at each fire, so filling
+   * in `calls` after the lead runs makes it visible to every row, including the `complete` ones.
+   *
+   * `signal` and `scope` were MISSING, and both are documented roots. That is not theoretical:
+   * `aws-s3/S3FileContent` reads `signal.key`, `signal.universalId` and `signal.etag` in its events
+   * row, and `flow/Context` reads `scope.*` — so both threw "unknown identifier" on every run. The
+   * sandbox refuses an undeclared identifier outright, so the row failed rather than reading empty.
+   *
+   * Kept in step with the roots `context.ts` documents; a row seeing less than a body template can is
+   * a trap, because the same expression works in one file and not the other.
+   */
+  const base: Record<string, unknown> = {
+    config: ctx.config,
+    user: ctx.user,
+    scope: ctx.scope,
+    signal: ctx.signal,
+    calls: {},
+  };
+  const emitter = makeEmitter(node, onEmit, base);
+
+  /**
+   * EVENTS-ONLY: there is no reply, so the rows fire over the SIGNAL.
+   *
+   * `response` is the incoming signal rather than a body, which is the only honest thing it
+   * can be: `IfElse` routes what arrived, and `Relay` passes it through. A row's `when` is
+   * what makes routing work — two rows, one per output dot, each testing the same condition.
+   *
+   * Returns before the request machinery, so nothing below it can reach for a `final` that
+   * does not exist.
+   */
+  if (eventsOnly) {
+    await emitter.response(ctx.signal ?? {});
+    const emissions = await emitter.finish();
+    const outputs = emitter.outputs();
+    await publishTemplateData(node, api, { ...base, output: outputs }, session);
+    return { outputs, emissions, status: 200 };
+  }
+
+  // Narration first, and on BOTH paths: it is a property of the node, not of tools.
+  const narrator = makeNarrator(node, ctx, emitter);
+  narrator.fire({ kind: "turnStart", userMessage: ctx.config?.prompt ?? "" });
+
+  try {
+    const { results, last } = lead.length
+      ? await runCalls(node, lead, ctx, node.type, store)
+      : { results: {} as Record<string, any>, last: undefined as any };
+    base.calls = results;
+    const scoped: RunContext = { ...ctx, calls: results };
+
+    // THE LAST CALL HONOURS ITS `when` LIKE EVERY OTHER ONE.
+    //
+    // It did not, and the failure was live rather than theoretical: HubSpot's last call
+    // writes queued notes to the CRM and is gated on a config toggle, so with that toggle
+    // OFF the node still POSTed to the notes endpoint on every run. Nothing errored,
+    // because the vendor accepted an empty write. A conditional call that fires anyway is
+    // worse than one that never fires, because the wrongness is invisible.
+    //
+    // Skipped, the node settles on the last call that DID run, which is what a reader
+    // expects of a list whose tail is optional.
+    const skipFinal = !!final.when && !(await evaluate(final.when, scoped as unknown as Record<string, unknown>));
+
+    let status = 200;
+    if (skipFinal) {
+      await emitter.response(last);
+    } else {
+      // No bridge means nothing granted this node tools. Normal (an mcp connector nobody
+      // wired), so it degrades to one ordinary call rather than failing.
+      /**
+       * `runToolLoop` is the HTTP tool loop and must NOT take a duplex node.
+       *
+       * It works by TURNS — send a request, read the tool calls out of the reply, send another —
+       * and a socket has no turns: the conversation never ended, so a tool result goes back down
+       * the same connection. A ws node declaring a toolExchange therefore stays on the duplex
+       * path, which resolves its calls inline. Without this check, declaring tools on the voice
+       * node would silently route it through HTTP and never open the socket at all.
+       */
+      const duplex = final.transport === "ws";
+      status = api.toolExchange && tools && !duplex
+        ? await runToolLoop(node, scoped, tools, emitter, narrator.fire, final, store)
+        : await runFinal(node, final, scoped, emitter, base, store, lane, tools);
+    }
+
+    const emissions = await emitter.finish();
+    const outputs = withSaveFlag(emitter.outputs(), api, base);
+    // The FULL settled reply, for the card lane: runFinal writes the final call's payload
+    // into base.calls under its name; on a skipped final the run settled on the lead's last.
+    const settled = (base.calls as Record<string, unknown>)[final.name] ?? last;
+    await publishTemplateData(node, api, { ...base, output: outputs }, session);
+    await renderRunComponents(node, api, { ...base, output: outputs, response: settled }, session);
+    return { outputs, emissions, status };
+  } finally {
+    narrator.settle();
+  }
+}
+
+/**
+ * `publish` — A GENERIC WRITE INTO THE CALLER'S TEMPLATE STATE, the workflow channel's
+ * sibling of the service channel's `renderComponents`: both reach the person watching rather
+ * than answer the graph, and both no-op when nobody is (builder, tests, headless, cron).
+ *
+ * AFTER the emitter settles, over `output`, deliberately: the pushed value derives from what
+ * the node actually emitted, so the screen and the graph cannot drift apart — a Suggestions
+ * whose connector carried one object and whose push carried another would be exactly the
+ * half-working that takes an afternoon to see.
+ *
+ * The frame is the one the retired Suggestions node sent and the client already handles
+ * (`connection.ts` APP_DATA): the client merges `data` opaquely into template state and
+ * knows no key names — the PRODUCER names them (UNOVERSE_STATE_MODEL §2/§8).
+ *
+ * SAY WHAT HAPPENED, always, for the same reason the card lane learned to: this no-ops three
+ * different ways (no session, nothing evaluated, nobody listening) and silence must not read
+ * as success.
+ */
+async function publishTemplateData(
+  node: ComposedNode,
+  api: NonNullable<ComposedNode["api"]>,
+  scope: Record<string, unknown>,
+  session?: CallerSession,
+): Promise<void> {
+  const spec = api.publish;
+  if (!spec) return;
+  if (spec.when && !(await evaluate(spec.when, scope))) return;
+  const data = await evaluate(spec.data, scope);
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    console.log(`[manifests] ${node.type}: publish evaluated to ${Array.isArray(data) ? "an array" : typeof data} — template state merges OBJECTS, nothing pushed`);
+    return;
+  }
+  if (!session?.userId || !session?.conversationId) {
+    console.log(`[manifests] ${node.type}: template data not pushed — no live session on this run`);
+    return;
+  }
+  const delivered = clientTransport().pushToClient(session.userId, session.conversationId, {
+    type: "APP_DATA",
+    chatId: session.chatId,
+    conversationId: session.conversationId,
+    userId: session.userId,
+    data,
+    timestamp: new Date().toISOString(),
+  });
+  console.log(
+    `[manifests] ${node.type}: template data ${delivered ? "pushed" : "found NO listener"} — keys: ${Object.keys(data as object).join(", ") || "(none)"}`,
+  );
+}
+
+/**
+ * `renderComponents` — THE RUN LANE'S CARD LANE, the workflow channel's sibling of the
+ * service channel's per-method `renderComponents` (service.ts, which this mirrors
+ * deliberately, same renderer): rows the run surfaced render as content cards
+ * on the caller's live screen, data-driven, never a model tool. Declared as
+ * api/renderComponents.yaml on the node.
+ *
+ * AFTER the events table settles, over the FULL reply: an events row is where a node
+ * projects its outputs down for the graph, and a card needs the full row (component uri,
+ * images, authored copy) that the projection strips. `response` in the scope is the final
+ * call's settled payload, never an output.
+ *
+ * Fire-and-forget and no-op without a live session, exactly like the service lane and
+ * `publish` above: a run nobody is watching should carry on, not throw. SAY WHAT HAPPENED,
+ * always, for the same reason the service lane learned to — this no-ops three different
+ * ways and silence must not read as success.
+ */
+async function renderRunComponents(
+  node: ComposedNode,
+  api: NonNullable<ComposedNode["api"]>,
+  scope: Record<string, unknown>,
+  session?: CallerSession,
+): Promise<void> {
+  if (!api.renderComponents) return;
+  const log = (m: string) => console.log(`[manifests] ${node.type}: ${m}`);
+  const rows = await evaluate(api.renderComponents, scope);
+  const sessionCtx = {
+    userId: session?.userId,
+    conversationId: session?.conversationId,
+    chatId: session?.chatId,
+    accessToken: session?.accessToken,
+  };
+  const found = rowComponentsFromResults(rows);
+  if (found.length) {
+    if (!session?.userId) log(`${found.length} row component(s) not rendered — no live session on this run`);
+    renderRowComponents(found, sessionCtx, log);
+  } else {
+    const n = Array.isArray(rows) ? rows.length : 0;
+    log(`no row components in ${n} row(s)`);
+    // The empty delivery is announced (§12e mechanical spent rule): this search
+    // ran and surfaced nothing, and the standing set's fate hangs on that fact.
+    renderRowComponents(found, sessionCtx, log);
+  }
+}
+
+/**
+ * `__saveToContext`, which the ENGINE reads off the output envelope.
+ *
+ * Two halves make one behaviour and both must happen or neither is any use: the `save` state op
+ * writes `saved:<executionId>` for a LATER run of the template resolver, and this flag tells
+ * `executingState` to put the same value into the in-memory cache so THIS run can see it too. The
+ * retired Code node set both by hand. Here the flag is DERIVED rather than declared, so a manifest
+ * cannot write the value and forget the flag — the value would be reachable next node but not this
+ * one, which is the sort of half-working that takes an afternoon to see.
+ *
+ * Derived from `base.calls`, not from the declaration: a call records its name there only if it
+ * actually RAN, so a save gated `when: config.saveToContext` correctly sets no flag when the toggle
+ * is off. That also makes it work the same whether the save is the last call or an earlier one,
+ * with nothing threaded through.
+ */
+function withSaveFlag(
+  outputs: Record<string, unknown>,
+  api: NonNullable<ComposedNode["api"]>,
+  base: Record<string, unknown>,
+): Record<string, unknown> {
+  const ran = base.calls as Record<string, unknown>;
+  const saved = (api.run ?? []).some((c: any) => c.state === "save" && ran[c.name] !== undefined);
+  return saved ? { ...outputs, __saveToContext: true } : outputs;
+}

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

@@ -0,0 +1,150 @@
+/**
+ * What a manifest may see at run time, and the resolvers applied before it does.
+ *
+ * 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.
+ */
+import type { ComposedNode } from "../compose.js";
+
+/** Everything a manifest's templates and expressions may see. */
+export interface RunContext {
+  config: Record<string, any>;
+  credentials: Record<string, any>;
+  /** Upstream node outputs, keyed signal.<sourceId>.<outputHandle>. */
+  signal: Record<string, any>;
+  /** Prompt blocks by camelCase name, so {{prompt.markdownGuidelines}} resolves. */
+  prompt: Record<string, string>;
+  /** Runtime service wiring, e.g. services.mcpService.tools. */
+  services: Record<string, any>;
+  /** Arguments a CALLER passed to a service method. Empty when the graph runs the node. */
+  params: Record<string, any>;
+  /**
+   * Replies from the calls made EARLIER in this run, keyed by each call's `name`.
+   *
+   * Empty for a node that makes one call. A call skipped by its `when` has no key at all,
+   * which is what lets a later call, an events row, or `returns` ask whether it happened.
+   *
+   * Named `calls` and not `steps` on purpose: a step is a node on a canvas, and reusing
+   * the word here would make "this node's steps" and "the workflow's steps" the same
+   * phrase for two different things.
+   */
+  calls: Record<string, any>;
+  /**
+   * The SIGNED-IN person, and nothing that authenticates as them.
+   *
+   * Identity only: email, id, name. The caller's `accessToken` is deliberately absent and
+   * must stay absent (see executor.ts contextFor). The distinction is the whole reason
+   * this scope can exist at all: a JWT IS the user against our own services, so a pasted
+   * manifest could send it to any allowed host, whereas an email authenticates nothing.
+   *
+   * It earns a first-class scope because "who is asking" is the join key for every CRM,
+   * support and account node, and reading it off the wire instead would let a caller
+   * fetch someone else's record.
+   */
+  user: { email?: string; id?: string; name?: string };
+  /**
+   * WHICH RUN this is, for keying platform state.
+   *
+   * `userId` is the PUBLISHING context's id, not `user.id`: the platform's own user id and
+   * the authenticated identity are different values, and the memory server keys its
+   * snapshot by the former. Using the wrong one writes to a key nobody reads, silently.
+   */
+  /**
+   * `conversationId` and `chatId` are the AUDIO LANE's keys, not decoration. A duplex voice node
+   * registers its microphone handler and sends the model's audio against the conversation, so
+   * without them the lane silently matches nothing: every frame in is dropped by an id comparison
+   * that cannot succeed, and every frame out goes to a conversation nobody is listening on. That
+   * failed with no error at all, which is why they are first-class here rather than read ad hoc.
+   */
+  /**
+   * `nodeId` is WHICH INSTANCE on the canvas, and it is here because two different things are
+   * keyed by it and neither can be derived from anything else in scope.
+   *
+   * A content-addressed id mixes it in, so two Code nodes computing the same value in the same
+   * workflow still mint different universal ids — which is the point, since they are different
+   * places in the graph. And the saved-context hash stores one field per node, so a later
+   * template reaches `saved.<nodeId>`. Without it both fall back to a constant and collide
+   * silently: the ids look stable while describing the wrong node.
+   */
+  /**
+   * `platformUrl` is THE PLATFORM'S OWN API, for the nodes that call US rather than a vendor.
+   *
+   * Most nodes reach a third party at a host they can name in `allowedHosts`. A growing few reach the
+   * engine instead — spatial ingestion hands raw text to the content pipeline, spatial search queries
+   * the dictionary — and that host is a DEPLOYMENT fact: localhost in dev, a service name in a cluster,
+   * a domain in production. A manifest cannot derive it and must never guess it.
+   *
+   * DERIVED from `UNOVERSE_RUNTIME_PORT`, which docker-compose already sets and the server already
+   * reads — a node runs INSIDE the service, so it is calling itself and needs no configuration to learn
+   * its own address. Loopback, because :4106 is the ungated internal listener and is published to
+   * 127.0.0.1 only.
+   */
+  scope: { userId?: string; workflowId?: string; conversationId?: string; chatId?: string; executionId?: string; nodeId?: string; platformUrl?: string; engineUrl?: string };
+  /**
+   * THE CONVERSATION SO FAR, for a tool loop against a vendor with no chain id.
+   *
+   * Empty except inside `runToolLoop`, and empty there on the first turn. It grows by the assistant's
+   * tool-call turn and one message per result, and a manifest spreads it into its own message array:
+   *
+   *     messages: [{ role: 'system', … }, { role: 'user', … }, ...transcript]
+   *
+   * It exists because Chat Completions — GLM, Grok, most OpenAI-COMPATIBLE vendors — resends the whole
+   * history every turn, where the Responses API hands back a `previous_response_id` and the next turn
+   * just names it. `continuity` models the latter; this models the former. The SHAPE of a message stays
+   * in the manifest, because it is the vendor's, not ours.
+   */
+  transcript: unknown[];
+  /**
+   * The skills in force, rendered for a system prompt. Empty except inside `runToolLoop`,
+   * and empty there until a search resolves the conversation into a region that has one.
+   * Read by a manifest as `{{ skillsText }}`, the same way `transcript` is spread into a
+   * message array: the platform decides WHICH skills apply, the manifest decides where the
+   * vendor wants them.
+   */
+  skillsText: string;
+
+  /**
+   * What an OAuth2 exchange returned, for the call it authenticated.
+   *
+   * Some vendors tell you WHERE to talk as well as how: Salesforce returns `instance_url`
+   * and the org's data lives there, not at the login host you authenticated against. Only
+   * populated for `oauth2ClientCredentials`, and never carries the token itself.
+   */
+  token: { instanceUrl?: string };
+}
+
+export function emptyContext(partial: Partial<RunContext> = {}): RunContext {
+  return { config: {}, credentials: {}, signal: {}, prompt: {}, services: {}, params: {}, calls: {}, user: {}, scope: {}, token: {}, transcript: [], skillsText: "", ...partial };
+}
+
+/** Config values a resolver rewrites just before the request is built. */
+export const RESOLVERS: Record<string, (value: any, node: ComposedNode) => any> = {
+  // Migration of shared/models.ts resolveModel(): a saved workflow stores a concrete
+  // model id, and if that id is retired this falls back to the current best model in
+  // the same tier. Without it, replacing a model generation breaks every saved
+  // workflow that named an old id.
+  modelTier(value: any, node: ComposedNode) {
+    const field = node.definition.configSchema?.properties?.model;
+    const options: string[] = field?.enum ?? [];
+    if (!value || options.includes(value)) return value || options[0];
+    const m = String(value).toLowerCase();
+    // Tier words cover both families the packages ship: GPT (luna/terra) and Claude
+    // (haiku/sonnet). Anything unrecognised lands on large, the safe over-provision.
+    const tier = /luna|mini|small|nano|haiku/.test(m) ? 0 : /terra|balanced|medium|sonnet/.test(m) ? 1 : 2;
+    // Options are listed large first, so index from the end for small.
+    const picked = [options[options.length - 1], options[1], options[0]][tier] ?? options[0];
+    console.warn(`[manifests] model "${value}" is no longer available — using "${picked}". Update this node.`);
+    return picked;
+  },
+};
+
+/** Apply every declared resolver to the config before templates see it. */
+export function applyResolvers(config: Record<string, any>, node: ComposedNode): Record<string, any> {
+  const props = node.definition.configSchema?.properties ?? {};
+  const out = { ...config };
+  for (const [name, spec] of Object.entries<any>(props)) {
+    const fn = spec?.resolve ? RESOLVERS[spec.resolve] : null;
+    if (fn) out[name] = fn(out[name], node);
+  }
+  return out;
+}