@unoverse-platform/studio 0.1.90 → 0.1.92

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

@@ -0,0 +1,110 @@
+/**
+ * Build what a manifest's templates and expressions may see.
+ *
+ * `config` arrives ALREADY RESOLVED: the engine runs its template resolver before it
+ * calls execute, so {{signal.x}} and {{prompt.y}} an author wrote in a config field are
+ * plain text by the time they reach here.
+ *
+ * `executionContext.auth.accessToken` — the CALLER'S JWT (AUTH_TOKEN_FLOW.md) — is
+ * DELIBERATELY WITHHELD, and must stay that way. A code node may reach it because a code
+ * node is bounded by provenance; a manifest is data that can arrive by paste or database
+ * row. The blast radii are not comparable: a third-party API key reaches that vendor
+ * account, while a platform JWT IS the user against our own services, so a pasted
+ * manifest could forward it to any host its allowedHosts list allows.
+ *
+ * `auth.user` — the signed-in person's email, id and name — IS exposed, as `user`. That
+ * is not a softening of the rule, it is the rule applied to a different thing: an email
+ * authenticates nothing, and it is the join key every CRM, support and account node needs.
+ * Withholding it would force those nodes to take identity off the WIRE, which is strictly
+ * worse: a caller could then ask for someone else's record. Never widen this to the token.
+ *
+ * The tool bridge DOES use the token, and that is not a contradiction: there the
+ * platform is calling its own internal /mcp on the user's behalf, rather than data
+ * deciding where a secret goes.
+ *
+ * EXPORTED ONLY FOR THE SIBLING FILES IN THIS FOLDER (the two executors and the re-fire).
+ * Nothing outside `executor/` may import it: every consumer of a RunContext outside this
+ * folder receives one already built, and a second builder is how the token rule would
+ * eventually be widened by accident. Pinned by manifest-chain.test.ts.
+ */
+import type { ComposedNode } from "../compose.js";
+import { applyResolvers, emptyContext, type RunContext } from "../runtime/index.js";
+
+export function contextFor(node: ComposedNode, inputs: any, config: any, executionContext: any): RunContext {
+  const user = executionContext?.auth?.user ?? {};
+  return emptyContext({
+    config: applyResolvers(config ?? {}, node),
+    // The bag holds EVERY credential in the workflow keyed by name. Selecting by name is
+    // the manifest's job, which is what stops a node authenticating with a neighbour's
+    // apiKey (04-credentials.md).
+    credentials: executionContext?.credentials ?? {},
+    signal: inputs ?? {},
+    services: executionContext?.services ?? {},
+    // The caller's disconnect. A tool loop stops between turns when it fires, so a run
+    // the engine reaped cannot keep spending model calls (observed live 2026-09-05).
+    abort: executionContext?.abortSignal,
+    // Picked field by field, never spread: a future field on auth.user must be an explicit
+    // decision to expose, not something a manifest silently inherits.
+    user: { email: user.email, id: user.id ?? user.sub, name: user.name },
+    // The PLATFORM's ids, which is what state keys are built from. Same precedence the
+    // retired CRM code used, and it is not interchangeable with user.id above.
+    //
+    // `conversationId` and `chatId` are here because the AUDIO LANE is keyed by conversation.
+    // Their absence was a silent, total failure of the voice node: `runDuplexSession` fell back
+    // to the node TYPE as its key, so `setAudioDataHandler` compared the client's real session id
+    // against the string "OpenAIRealtimeVoice", dropped every microphone frame, and sent the
+    // model's audio to a conversation nobody was listening on. No error anywhere — just silence.
+    //
+    // Same precedence the retired node used: publishingContext first, then workflow variables.
+    scope: {
+      userId: executionContext?.publishingContext?.userId ?? executionContext?.workflow?.variables?.userId,
+      workflowId: executionContext?.workflowId ?? executionContext?.workflow?.id,
+      conversationId:
+        executionContext?.publishingContext?.conversationId ?? executionContext?.workflow?.variables?.conversationId,
+      chatId: executionContext?.publishingContext?.chatId ?? executionContext?.workflow?.variables?.chatId,
+      executionId: executionContext?.executionId,
+      // Which INSTANCE on the canvas. The retired Code node fell back to the literal "code" when
+      // this was missing, which meant two Code nodes minted the same universal id and the saved
+      // context stored them under one key. Passing it through rather than defaulting is what makes
+      // that failure impossible instead of merely unlikely.
+      nodeId: executionContext?.nodeId,
+      /**
+       * THE PLATFORM'S OWN API, for a node that calls us rather than a vendor.
+       *
+       * DERIVED, not configured. A node runs INSIDE the unoverse service, so it is calling itself —
+       * asking a developer to supply the platform's own address would be configuration for something
+       * the process already knows. `UNOVERSE_RUNTIME_PORT` is the internal listener and is already set
+       * in docker-compose; the server reads it the same way (`RUNTIME_PORT`), and already builds its own
+       * loopback url as `http://127.0.0.1:${port}` elsewhere.
+       *
+       * LOOPBACK, not a service name: :4106 is the UNGATED internal listener, published to 127.0.0.1
+       * only and never widened. Reaching it from anywhere else would be a mistake, so the address says
+       * so.
+       *
+       * The retired SpatialIngest read UNOVERSE_SERVICE_URL with a `|| "http://localhost:4106"`
+       * fallback — a variable that is set NOWHERE in this repo, so the fallback was the whole
+       * behaviour. Deriving it removes both the dead variable and the hardcoded string.
+       */
+      platformUrl: `http://127.0.0.1:${process.env.UNOVERSE_RUNTIME_PORT ?? 4106}`,
+      /**
+       * THE ENGINE, on :4101, and it is NOT the same service as `platformUrl`.
+       *
+       * Two internal listeners, two different sets of routes, and picking the wrong one is a
+       * 404 rather than anything that reads like an address problem:
+       *
+       *   :4106  the unoverse runtime  — /service-call, /execute, /skills
+       *   :4101  the engine            — /spatial/search, /dictionary/entry, /workflows
+       *
+       * SpatialSearch needs BOTH, which is what makes the distinction worth a second field
+       * rather than a note: its searches are engine routes and its skill reads are runtime
+       * routes. The retired node had the same split and hid it in two different env vars
+       * (WORKFLOW_SERVICE_URL and UNOVERSE_SERVICE_URL), neither of which is set anywhere in
+       * this repo, so both fallbacks were the entire behaviour.
+       *
+       * Same derivation as above, and the same reasoning: loopback because these listeners
+       * are internal and never published, and derived so there is no dead variable to set.
+       */
+      engineUrl: `http://127.0.0.1:${process.env.ENGINE_PORT ?? process.env.WORKFLOW_SERVICE_PORT ?? 4101}`,
+    },
+  });
+}

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

@@ -0,0 +1,47 @@
+/**
+ * The TWO executors every manifest node shares.
+ *
+ * There are exactly two, not one per node. A node's identity, ports, config and
+ * selection text are DATA in the registry; the code that performs it is one of these
+ * classes. Which one is decided by `kind`, and the split exists only because the
+ * platform genuinely has two execution shapes: settle-once (PromiseNode) and
+ * emit-repeatedly (CallbackNode). The registry itself derives executionMode by
+ * checking whether the prototype has initializeState, so the shapes cannot be merged.
+ *
+ * They are STATELESS with respect to which node they are running. The manifest is
+ * looked up by nodeType at execution time rather than closed over at registration
+ * (lookup.ts), which is what keeps this at two classes instead of one per manifest. It
+ * also means a reload swaps behaviour with no re-registration: the class stays, the
+ * data moves.
+ *
+ * ONE FILE PER JOB:
+ *
+ *   lookup.ts       how an executor finds its manifest by node type
+ *   context.ts      what a MANIFEST may see — and the token it must never see
+ *   session.ts      what the executor hands to PLATFORM code (session, state, audio)
+ *   toolBridge.ts   the agent harness, bridged into the tool loop
+ *   refire.ts       the hybrid contract: a doc mutation re-fires the workflow channel
+ *   promise.ts      settle-once
+ *   callback.ts     emit-repeatedly
+ *
+ * `contextFor` is deliberately NOT re-exported here: everything outside this folder
+ * receives a RunContext already built, and a second builder is how the token rule would
+ * eventually be widened by accident.
+ */
+import type { ComposedNode } from "../compose.js";
+import { ManifestPromiseExecutor } from "./promise.js";
+import { ManifestCallbackExecutor } from "./callback.js";
+
+export { setManifestLookup } from "./lookup.js";
+export { ManifestPromiseExecutor } from "./promise.js";
+export { ManifestCallbackExecutor } from "./callback.js";
+
+/**
+ * The class a node of this kind registers.
+ *
+ * Returns one of the two shared classes. The registry stores the class and
+ * constructs it with the node type, so nothing here is per-manifest.
+ */
+export function executorForKind(kind: ComposedNode["kind"]): any {
+  return kind === "CallbackNode" ? ManifestCallbackExecutor : ManifestPromiseExecutor;
+}

package/vendor/base/src/manifests/executor/lookup.ts

@@ -0,0 +1,21 @@
+/**
+ * HOW AN EXECUTOR FINDS ITS MANIFEST. The two executor classes are stateless with respect
+ * to which node they are running: the manifest is looked up by nodeType at execution time
+ * rather than closed over at registration, which is what keeps the platform at two classes
+ * instead of one per manifest — and what makes a reload swap behaviour with no
+ * re-registration: the class stays, the data moves.
+ */
+import type { ComposedNode } from "../compose.js";
+
+/** Set by the loader so both executors can resolve their manifest by node type. */
+let lookup: (type: string) => ComposedNode | undefined = () => undefined;
+
+export function setManifestLookup(fn: (type: string) => ComposedNode | undefined): void {
+  lookup = fn;
+}
+
+export function manifestFor(type: string): ComposedNode {
+  const node = lookup(type);
+  if (!node) throw new Error(`No manifest loaded for node type "${type}" — it may have been unloaded mid-run.`);
+  return node;
+}

package/vendor/base/src/manifests/executor/memory.ts

@@ -0,0 +1,62 @@
+/**
+ * THE MEMORY LANES — the two harness calls every legacy agent made and the manifest
+ * executor stopped making, which is how the memory system sat healthy-but-idle after the
+ * migration: a running memory server, an empty ingest stream, and toggles that had
+ * vanished from the UI because no manifest declared them.
+ *
+ * Wired at the EXECUTOR, not in any manifest, mirroring how the engine injects the
+ * goal-memory toolset from the same flags (PlatformMemoryCore): a node declares
+ * `enableUserMemory` / `enableAgentMemory` in its config and the platform does the rest.
+ * Both lanes self-gate on the toggle and on identity, so a node without the fields, a
+ * bench run, or a headless caller costs nothing.
+ *
+ * The implementations live in ../../agent-mcp (memoryContext.ts / memoryIngest.ts) —
+ * they moved there in the harness extraction and are TRANSCRIBED conventions:
+ * hydration prepends the user's context snapshot to the USER PROMPT (never the system
+ * prompt — facts that ride the request refresh every turn and survive prompt caching),
+ * and ingest saves original input + final answer, never tool chatter.
+ */
+
+/** Prepend the user's memory context to config.prompt when the toggle is on. */
+export async function hydrateMemory(config: any, executionContext: any): Promise<any> {
+  if (config?.enableUserMemory !== true || typeof config?.prompt !== "string") return config;
+  try {
+    const harness: any = await import("../../agent-mcp/index.js");
+    const prompt = await harness.hydratePromptWithUserMemory(config, executionContext, console, config.prompt);
+    return prompt === config.prompt ? config : { ...config, prompt };
+  } catch (e: any) {
+    // Non-blocking, exactly as the legacy hydration was: memory enriches a run, it
+    // never gates one.
+    console.log(`[manifests] user-memory hydration failed (non-blocking): ${e?.message ?? e}`);
+    return config;
+  }
+}
+
+/**
+ * Save the completed turn (original input + final answer) to the memory server.
+ * Fire-and-forget; `ingestConversationTurn` itself gates on the toggle and identity.
+ * The answer is read off the node's own outputs — `text` is the settled connector on
+ * every agent family (the streamed `stream` connector carries the same final value).
+ */
+export async function ingestMemoryTurn(
+  nodeType: string,
+  config: any,
+  executionContext: any,
+  outputs: Record<string, unknown>,
+): Promise<void> {
+  if (config?.enableUserMemory !== true) return;
+  const answer = outputs?.text ?? outputs?.stream ?? outputs?.output;
+  if (typeof answer !== "string" || !answer) return;
+  try {
+    const harness: any = await import("../../agent-mcp/index.js");
+    harness.ingestConversationTurn(
+      config,
+      executionContext,
+      { userMessage: String(config?.prompt ?? ""), agentResponse: answer },
+      console,
+      nodeType,
+    );
+  } catch (e: any) {
+    console.log(`[manifests] memory ingest failed (non-blocking): ${e?.message ?? e}`);
+  }
+}

package/vendor/base/src/manifests/executor/promise.ts

@@ -0,0 +1,71 @@
+/** Settle-once. One request, one result. */
+import { performApi, performService } from "../runtime/index.js";
+import { deliverSends } from "./send.js";
+import { assertAuthorized } from "../runtime/authorize.js";
+import { manifestFor } from "./lookup.js";
+import { contextFor } from "./context.js";
+import { sessionFor, stateStoreFor } from "./session.js";
+import { refireAfterDocMutation } from "./refire.js";
+import { toolBridgeFor } from "./toolBridge.js";
+
+export class ManifestPromiseExecutor {
+  logger: any = console;
+  constructor(readonly nodeType: string) {}
+
+  /**
+   * The SERVICE channel: a method another node called over a service edge.
+   *
+   * Independent of the workflow channel. A service call returns a value to the caller
+   * and does NOT fire this node's output connectors; a graph trigger fires the outputs
+   * and does not answer a caller. The two never cross (08-mcp-services.md).
+   */
+  async handleServiceCall(method: string, params: any, config: any, executionContext: any): Promise<unknown> {
+    const node = manifestFor(this.nodeType);
+    // The service channel is gated too, and it is the one that would be missed. A node
+    // reached over a service edge never fires its own connectors, so it is easy to think of
+    // as an internal detail of the caller. It is not: it runs this node's calls with this
+    // node's credentials, and leaving it open would make a service edge the way around a
+    // role rather than a way to reuse a capability.
+    assertAuthorized(node, executionContext, config);
+    const result = await performService(
+      node,
+      method,
+      params ?? {},
+      contextFor(node, {}, config, executionContext),
+      stateStoreFor(executionContext),
+      // The caller's live session, for a method that renders content cards. Assembled HERE
+      // because the token is deliberately absent from the manifest's context and must stay
+      // that way: the executor holds it and hands it to platform code, never to the manifest.
+      sessionFor(executionContext),
+    );
+    await refireAfterDocMutation(node, method, config, executionContext);
+    return result;
+  }
+
+  async execute(inputs: any, config: any, executionContext: any): Promise<{ __outputs: Record<string, unknown> }> {
+    const node = manifestFor(this.nodeType);
+    // BEFORE anything is built or sent, so a refused run costs no vendor request, no token,
+    // and no side effect. Authorization that runs after the call has gone out is an audit
+    // log, not a gate.
+    assertAuthorized(node, executionContext, config);
+    const { outputs, emissions } = await performApi(
+      node,
+      contextFor(node, inputs, config, executionContext),
+      () => {},
+      node.api?.toolExchange ? await toolBridgeFor(executionContext) : undefined,
+      stateStoreFor(executionContext),
+      // No audio lane on the promise path (a duplex session is always a CallbackNode).
+      undefined,
+      // The caller's live session, for a node that publishes template data. Assembled here
+      // for the same reason as the service channel's: the executor holds the identity and
+      // hands it to platform code, never to the manifest.
+      sessionFor(executionContext),
+    );
+    // Any `send` row addressed a NODE rather than a connector: deliver those before settling,
+    // so a loop's next pass is already queued when this node reports done.
+    await deliverSends(node, emissions, executionContext);
+    // Outputs go back TOP-LEVEL under __outputs; anything else never reaches a
+    // downstream node.
+    return { __outputs: outputs };
+  }
+}

package/vendor/base/src/manifests/executor/refire.ts

@@ -0,0 +1,34 @@
+/**
+ * THE HYBRID CONTRACT (Pattern C, 08-mcp-services.md): a service method that MUTATED the
+ * node's document re-fires the WORKFLOW channel, so a downstream renderer receives the
+ * fresh markdown without the agent doing anything. Read methods must not re-fire — the
+ * retired SmartDocument learned that live, when every outline() re-emitted the whole
+ * document and flooded the renderer.
+ *
+ * Detection is by the method's own call list naming a mutating docstore op, so the manifest
+ * cannot promise the contract and forget it: declaring the op IS declaring the re-fire.
+ *
+ * `executeNodeWithRouting` is the engine's own bridge (NodeExecutionUtils), reached through
+ * the plugin api exactly as the retired executor reached it via getPlatform(). Absent
+ * (tests, headless) the mutation still returns to the caller — the render is a side channel
+ * and failures here are logged, never thrown, exactly as the retired node treated them.
+ */
+import { performApi, MUTATING_DOC_OPS } from "../runtime/index.js";
+import { contextFor } from "./context.js";
+import { stateStoreFor } from "./session.js";
+
+export async function refireAfterDocMutation(node: any, method: string, config: any, executionContext: any): Promise<void> {
+  const calls = node.api?.service?.[method]?.calls ?? [];
+  if (!calls.some((c: any) => c.docstore && MUTATING_DOC_OPS.has(String(c.docstore)))) return;
+  const route = executionContext?.api?.executeNodeWithRouting;
+  if (typeof route !== "function") return;
+  const run = async (_inputs: any, cfg: any, ec: any) => {
+    const { outputs } = await performApi(node, contextFor(node, {}, cfg, ec), () => {}, undefined, stateStoreFor(ec));
+    return { __outputs: outputs };
+  };
+  try {
+    await route(run, {}, config, executionContext);
+  } catch (e: any) {
+    console.log(`[manifests] ${node.type}: post-mutation re-fire failed — ${e?.message ?? e}`);
+  }
+}

package/vendor/base/src/manifests/executor/send.ts

@@ -0,0 +1,65 @@
+/**
+ * `send` rows — one node handing a payload to a NAMED node, with no connector and no edge.
+ *
+ * WHY THIS EXISTS. LoopEnd already names its partner in `loopStartNodeId`. Requiring an edge as
+ * well made the same fact true in two places, and the two could disagree: the canonical loop
+ * pattern shipped without the edge for months, which builds a loop that runs exactly one pass and
+ * looks like it worked. A row that addresses a node removes the second place.
+ *
+ * It is deliberately NOT loop-specific. "Deliver this to that node" is the general primitive;
+ * the loop is its first caller.
+ *
+ * DELIVERY HAPPENS HERE, at the executor boundary, and not in events.ts. The events table
+ * DESCRIBES what leaves a node; performing a side effect needs the execution context, which only
+ * an executor holds. Keeping the split means a manifest still cannot reach the engine directly.
+ *
+ * FAILURE IS LOUD. A send that silently does nothing is a loop that stops after one pass while
+ * reporting success, which is the exact failure this replaced. An unresolvable target or an
+ * absent host raises, in the same spirit as `loop: advance` raising "loop state not found"
+ * rather than returning done.
+ */
+import type { Emission } from "../runtime/http/response.js";
+
+/**
+ * The host's delivery bridge. Absent in tests and headless runs.
+ *
+ * SAME RUN ONLY, and that is the point of the leading `executionId`: it is the SENDER's own,
+ * taken from its execution context, so a node can only ever reach nodes in the workflow it is
+ * running in. There is no addressing scheme that reaches another execution.
+ */
+type DeliverToNode = (
+  executionId: string,
+  targetNodeId: string,
+  handle: string,
+  value: unknown,
+) => Promise<void> | void;
+
+/**
+ * Deliver every `send` emission this run produced. A no-op for a node that declares none, which
+ * is every node but LoopEnd today, so this costs nothing on the common path.
+ */
+export async function deliverSends(node: any, emissions: Emission[], executionContext: any): Promise<void> {
+  const sends = emissions.filter((e) => e.to);
+  if (sends.length === 0) return;
+
+  const deliver: DeliverToNode | undefined = executionContext?.api?.deliverToNode;
+  if (typeof deliver !== "function") {
+    throw new Error(
+      `${node?.type ?? "node"}: an events row sends to another node, but this runtime provides no ` +
+        `deliverToNode bridge, so the message would be dropped. The run is stopped rather than ` +
+        `continuing with a message nobody received.`,
+    );
+  }
+
+  const executionId = executionContext?.executionId ?? executionContext?.scope?.executionId;
+  if (!executionId) {
+    throw new Error(
+      `${node?.type ?? "node"}: an events row sends to another node, but this run has no executionId, ` +
+        `so the delivery could not be confined to this workflow.`,
+    );
+  }
+
+  for (const s of sends) {
+    await deliver(String(executionId), String(s.to), s.handle ?? "input", s.value);
+  }
+}

package/vendor/base/src/manifests/executor/session.ts

@@ -0,0 +1,46 @@
+/**
+ * WHAT THE EXECUTOR ASSEMBLES FROM THE EXECUTION CONTEXT and hands to PLATFORM code —
+ * never to the manifest. `context.ts` builds what a manifest may READ; these build what
+ * the runtime's own capabilities need, and the difference is exactly the token rule:
+ * `sessionFor` carries the caller's JWT because the platform calling its own surface on
+ * the user's behalf is not data deciding where a secret goes.
+ */
+import { makeStateStore } from "../runtime/index.js";
+
+/**
+ * WHO IS WATCHING, for a service method that renders content cards onto a live screen or
+ * a node that publishes template data.
+ *
+ * Kept out of `contextFor` on purpose (§9.4): a manifest that could read the token could
+ * forward it anywhere its allowedHosts allows.
+ *
+ * `publishingContext` is the trigger-supplied identity of the conversation the run belongs
+ * to. Absent for builder, test and headless callers, which is exactly when card rendering
+ * should no-op rather than needing a flag.
+ */
+export function sessionFor(executionContext: any) {
+  const pub = executionContext?.publishingContext;
+  return {
+    userId: pub?.userId,
+    conversationId: pub?.conversationId,
+    chatId: pub?.chatId,
+    accessToken: executionContext?.auth?.accessToken,
+  };
+}
+
+/**
+ * The platform's audio lane, through the same handle a code node already gets.
+ *
+ * `null` when the platform has no lane, and that is NOT an error: a voice node with nowhere to
+ * send audio still holds a valid conversation with the vendor, and its transcripts still reach
+ * the workflow over the events table. Only the audio is lost, which is the correct degradation
+ * for a headless run.
+ */
+export function audioLaneFor(executionContext: any) {
+  return executionContext?.api?.getAudioWebSocketManager?.() ?? null;
+}
+
+/** Redis, through the handle the plugin library already provides to a code node. */
+export function stateStoreFor(executionContext: any) {
+  return makeStateStore(executionContext?.api?.getRedisClient?.() ?? null, process.env.REDIS_NAMESPACE);
+}