@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/manifests/source.ts

@@ -0,0 +1,196 @@
+/**
+ * Where node manifests come from.
+ *
+ * A SOURCE is deliberately an interface with one method, because the manifest
+ * format only pays off if a node can be installed and updated without restarting a
+ * universe. Disk is the source today; Postgres is the one that matters, and it must
+ * be able to arrive without touching anything downstream of here.
+ *
+ * Everything past this file works on the composed definition and never learns where
+ * it came from.
+ *
+ * See docs/architecture/DECLARATIVE_NODES.md.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+/** One node folder's raw files, before composition. */
+export interface RawNode {
+  /** Folder name. Should equal the node's `type`. */
+  dir: string;
+  /** Absolute path, or a synthetic id for non-disk sources. Used for $ref bases and errors. */
+  origin: string;
+  /**
+   * The node's yaml, flat. A section split across a folder appears with its path
+   * kept: "api/run.yaml". One level only, since a section has keys, not a tree.
+   */
+  files: Record<string, string>;
+  /**
+   * The content hash recorded when this node was PUBLISHED, if the source has one.
+   *
+   * Absent for disk, and that is correct rather than a gap: manifests in the monorepo are
+   * governed by git, which beats a hash file living beside the thing it protects. The
+   * check exists for rows, where there is no commit history and no review (SECURITY.md
+   * §"Manifest integrity").
+   */
+  hash?: string;
+}
+
+export interface RawPackage {
+  /** Package id, e.g. "openai". */
+  name: string;
+  origin: string;
+  /** package.yaml, if present. */
+  packageFile?: string;
+  /** credentials/<name>.yaml → contents. */
+  credentials: Record<string, string>;
+  /** shared/<name>.yaml → contents, for $ref resolution. */
+  shared: Record<string, string>;
+  nodes: RawNode[];
+}
+
+export interface ManifestSource {
+  /** For logs: "disk", "postgres". */
+  readonly name: string;
+  listPackages(): Promise<RawPackage[]>;
+}
+
+const YAML_RE = /\.ya?ml$/;
+const read = (p: string) => fs.readFileSync(p, "utf-8");
+
+/**
+ * Manifests from the `items` table: the source that makes installing a node an EFFECT
+ * rather than a record.
+ *
+ * A row stores the raw manifest exactly as authored (its files, plus the package
+ * envelope its $refs resolve against), so composition downstream is bit-for-bit the
+ * same work it does for disk. That is the point: one composition path means a node
+ * installed from a row and the same node read from a folder cannot diverge.
+ *
+ * Rows arrive grouped by package, because a package's credentials and shared fragments
+ * are shared by its nodes and composing one without them would fail on a $ref.
+ */
+export interface ItemRow {
+  name: string;
+  /**
+   * The hash recorded at publish. A COLUMN, not a key inside `definition`: the whole job
+   * of this value is to be compared against a hash computed from `definition`, so it must
+   * not be part of what is hashed.
+   */
+  hash?: string | null;
+  definition: {
+    package?: { name?: string; packageFile?: string | null; credentials?: Record<string, string>; shared?: Record<string, string> };
+    dir?: string;
+    files?: Record<string, string>;
+  };
+}
+
+export function rowsSource(fetchRows: () => Promise<ItemRow[]>): ManifestSource {
+  return {
+    name: "postgres",
+    async listPackages(): Promise<RawPackage[]> {
+      const rows = await fetchRows();
+      const byPackage = new Map<string, RawPackage>();
+
+      for (const row of rows) {
+        const d = row.definition;
+        if (!d?.files?.["node.yaml"]) continue; // not a manifest node row
+        const pkgName = d.package?.name ?? "unknown";
+
+        let pkg = byPackage.get(pkgName);
+        if (!pkg) {
+          pkg = {
+            name: pkgName,
+            origin: `postgres:${pkgName}`,
+            packageFile: d.package?.packageFile ?? undefined,
+            credentials: d.package?.credentials ?? {},
+            shared: d.package?.shared ?? {},
+          nodes: [],
+          };
+          byPackage.set(pkgName, pkg);
+        }
+
+        pkg.nodes.push({
+          dir: d.dir ?? row.name,
+          origin: `postgres:${pkgName}/${row.name}`,
+          files: d.files,
+          hash: row.hash ?? undefined,
+        });
+      }
+
+      return [...byPackage.values()];
+    },
+  };
+}
+
+/**
+ * Manifests on disk: <home>/<package>/nodes/<Node>/*.yaml
+ *
+ * A package with no `nodes/` folder is skipped entirely, so a pure-code package
+ * costs nothing here. A MIXED package (some manifest nodes, some code) is normal
+ * during migration and loads through both paths.
+ */
+export function diskSource(home: string): ManifestSource {
+  return {
+    name: "disk",
+    async listPackages(): Promise<RawPackage[]> {
+      return readDiskPackages(home);
+    },
+  };
+}
+
+/**
+ * The same read, synchronous. Disk settles at once; the source above is async only
+ * because the row source beside it must be. The publish collector (items/collect.ts) is
+ * synchronous end to end, so it reads here rather than growing a promise it cannot await.
+ */
+export function readDiskPackages(home: string): RawPackage[] {
+      if (!fs.existsSync(home)) return [];
+      const packages: RawPackage[] = [];
+
+      for (const entry of fs.readdirSync(home, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+        const pkgDir = path.join(home, entry.name);
+        const nodesDir = path.join(pkgDir, "nodes");
+        // A package earns a look if it has manifest nodes OR credential manifests.
+        // Credentials are declared per package and are NOT conditional on any node
+        // being migrated: skipping on `nodes/` alone would drop a package's
+        // credential types the moment its last manifest node was removed.
+        if (!fs.existsSync(nodesDir) && !fs.existsSync(path.join(pkgDir, "credentials"))) continue;
+
+        const pkg: RawPackage = {
+          name: entry.name,
+          origin: pkgDir,
+          packageFile: fs.existsSync(path.join(pkgDir, "package.yaml")) ? read(path.join(pkgDir, "package.yaml")) : undefined,
+          credentials: {},
+          shared: {},
+          nodes: [],
+        };
+
+        for (const [folder, into] of [["credentials", pkg.credentials], ["shared", pkg.shared]] as const) {
+          const dir = path.join(pkgDir, folder);
+          if (!fs.existsSync(dir)) continue;
+          for (const f of fs.readdirSync(dir).filter((f) => YAML_RE.test(f))) into[f] = read(path.join(dir, f));
+        }
+
+        for (const nodeEntry of fs.existsSync(nodesDir) ? fs.readdirSync(nodesDir, { withFileTypes: true }) : []) {
+          if (!nodeEntry.isDirectory()) continue;
+          const nodeDir = path.join(nodesDir, nodeEntry.name);
+          const files: Record<string, string> = {};
+          for (const f of fs.readdirSync(nodeDir, { withFileTypes: true })) {
+            // A section may be ONE file or a FOLDER of one file per key. A big api.yaml
+            // is several independent calls stacked in a single file; splitting them is
+            // how a person edits one call without reading the other three.
+            if (f.isDirectory()) {
+              for (const inner of fs.readdirSync(path.join(nodeDir, f.name)).filter((i) => YAML_RE.test(i)))
+                files[`${f.name}/${inner}`] = read(path.join(nodeDir, f.name, inner));
+            } else if (YAML_RE.test(f.name)) files[f.name] = read(path.join(nodeDir, f.name));
+          }
+          if (!files["node.yaml"]) continue; // not a manifest node
+          pkg.nodes.push({ dir: nodeEntry.name, origin: nodeDir, files });
+        }
+
+        if (pkg.nodes.length || Object.keys(pkg.credentials).length) packages.push(pkg);
+      }
+      return packages;
+}

package/vendor/base/src/manifests/watch.ts

@@ -0,0 +1,67 @@
+/**
+ * Watch node manifests and reload them on change. Development only.
+ *
+ * A manifest is data, so editing one should behave like editing design/ — save the file,
+ * see the change. Needing a restart would make the format feel worse than the code it
+ * replaces, when the whole argument for it is that data can move without a deploy.
+ *
+ * NOT enabled in production: there, manifests arrive through the marketplace or a
+ * database row, both of which already call the loader themselves. A filesystem watcher
+ * on a server nobody edits by hand is a way to reload half-written files.
+ *
+ * Uses node:fs.watch, which is native and free. No dependency for a dev nicety.
+ */
+import * as fs from "fs";
+import { loadManifests } from "./index.js";
+import { NODES_HOME } from "../paths.js";
+import { boot } from "../boot.js";
+
+let watcher: fs.FSWatcher | null = null;
+let pending: NodeJS.Timeout | null = null;
+
+/**
+ * Start watching, unless already watching or in production.
+ *
+ * `onReloaded` is where the engine's catalog snapshot gets refreshed — without it the
+ * server has the new node and Canvas still shows the old catalog, which reads as "the
+ * reload did not work".
+ */
+export function watchManifests(onReloaded?: () => Promise<void> | void): void {
+  if (watcher || process.env.NODE_ENV === "production") return;
+  if (!fs.existsSync(NODES_HOME)) return;
+
+  try {
+    watcher = fs.watch(NODES_HOME, { recursive: true }, (_event, filename) => {
+      if (!filename || !/\.ya?ml$/.test(filename)) return;
+
+      // Editors write a file in several operations (temp file, rename, truncate), so a
+      // single save fires repeatedly. Debounce, or a reload reads a half-written file.
+      if (pending) clearTimeout(pending);
+      pending = setTimeout(async () => {
+        pending = null;
+        try {
+          const result = await loadManifests();
+          console.log(`[unoverse:manifests] reloaded after ${filename}: ${result.nodes} node(s)`);
+          for (const e of result.errors) console.warn(`  ⚠ ${e}`);
+          await onReloaded?.();
+        } catch (err: any) {
+          // A reload must never take the server down: a half-typed manifest is a
+          // normal state while someone is editing one.
+          console.warn(`[unoverse:manifests] reload failed: ${err?.message ?? err}`);
+        }
+      }, 250);
+    });
+    boot.watching(NODES_HOME);
+  } catch (err: any) {
+    // recursive:true is unsupported on some platforms; a missing watcher is a lost dev
+    // nicety, never a failure to boot.
+    console.warn(`[unoverse:manifests] could not watch for changes: ${err?.message ?? err}`);
+  }
+}
+
+export function stopWatchingManifests(): void {
+  watcher?.close();
+  watcher = null;
+  if (pending) clearTimeout(pending);
+  pending = null;
+}

package/vendor/base/src/markdown/document.ts

@@ -0,0 +1,141 @@
+/**
+ * UNOVERSE MARKDOWN — a document SHAPED FOR THE RENDERER: areas into tabs, and the text
+ * projection for anything wanting words.
+ *
+ * Moved out of `agent-mcp/` because it was never the agent harness's: it is the render half
+ * of Unoverse Markdown, and it sat under the harness only because content cards were the
+ * first thing to need it. The schema half is beside it now.
+ */
+
+/**
+ * Mark the first section of each group, so a renderer can print the group label once.
+ *
+ * A repeated template cannot see the item before it, which is how a hand-written renderer
+ * decided this in React. Deriving it into the DATA keeps the rule in one place and gives
+ * every surface the same answer.
+ */
+export function withGroupStarts<T>(sections: T): T {
+  if (!Array.isArray(sections)) return sections;
+  let previous = "";
+  return sections.map((s) => {
+    const section = (s ?? {}) as Record<string, unknown>;
+    const group = typeof section.group === "string" ? section.group : "";
+    const groupStart = Boolean(group) && group !== previous;
+    if (group) previous = group;
+    return { ...section, groupStart };
+  }) as unknown as T;
+}
+
+/** How many tab slots the Document component authors. Four is a strip a reader takes in at
+ *  a glance; beyond that the tabs stop helping. Later groups fold into the last tab rather
+ *  than disappearing. */
+export const MAX_TABS = 4;
+
+/**
+ * Shape a record's sections for the Document component.
+ *
+ * SDUI switches on STATIC case names, and a group label is whatever the source called it,
+ * so tabs are addressed by POSITION: `tab0`…`tab5`, each with its own label. Flat, static,
+ * and renderable by a component that cannot know a group's name in advance.
+ *
+ * Two rules carried over from the renderer this replaces, because both are load-bearing:
+ * ungrouped material stays above the tabs (what the offering IS is never hidden behind
+ * one), and fine print appears on every tab rather than only the one it happened to land in.
+ */
+export function toDocument(sections: unknown, layout?: string): Record<string, unknown> {
+  const list = (Array.isArray(sections) ? sections : []) as Record<string, unknown>[];
+
+  const groups: string[] = [];
+  for (const s of list) {
+    const g = typeof s?.group === "string" ? s.group : "";
+    if (g && !groups.includes(g)) groups.push(g);
+  }
+
+  // The layout pass decides. Absent a decision, tabs earn their interaction cost only when
+  // there is enough material that one page would be a wall.
+  const tabbed = groups.length >= 2 && (layout === "tabs" || (!layout && list.length > 4));
+  if (!tabbed) {
+    // ONE group is not a grouping: a lone label applied to every section says nothing and
+    // would print an eyebrow over the whole document. Drop it and read as one page.
+    const flat = groups.length < 2 ? list.map((s) => ({ ...s, group: "" })) : list;
+    return { tabbed: false, sections: withGroupStarts(flat) };
+  }
+
+  // FINE PRINT, DEDUPED. It repeats into every tab, so two components carrying the same
+  // words print that text twice per tab. A source that says "Terms and conditions apply"
+  // under each of its benefits is not stating two different things.
+  const seenFine = new Set<string>();
+  const finePrint = list.filter((s) => {
+    if (s.kind !== "finePrint") return false;
+    const key = String(s.body ?? "").trim().toLowerCase().replace(/[\s.]+$/, "");
+    if (!key || seenFine.has(key)) return key ? false : true;
+    seenFine.add(key);
+    return true;
+  });
+
+  // WHAT LEADS IS WHAT COMES FIRST, not everything unlabelled. The rule is "material that
+  // introduces the offering is never hidden behind a tab", and introductory material is at
+  // the TOP. Leading every unlabelled component pulled a stray from the middle of the
+  // document up above the tab strip (observed live: a Protection list the model forgot to
+  // label rendered above the tabs, ahead of the opening paragraph).
+  const firstGrouped = list.findIndex((s) => typeof s.group === "string" && s.group);
+  const leadEnd = firstGrouped === -1 ? list.length : firstGrouped;
+  const out: Record<string, unknown> = {
+    tabbed: true,
+    lead: withGroupStarts(list.slice(0, leadEnd).filter((s) => !s.group && s.kind !== "finePrint")),
+    // ALWAYS carried, even tabbed. The component switches on `tabbed` and ignores it, but a
+    // host asking "does this record have a body?" has one field to look at either way. A
+    // card guarding on `sections` rendered nothing for a tabbed record without it.
+    sections: withGroupStarts(list),
+  };
+
+  const shown = groups.slice(0, MAX_TABS);
+  shown.forEach((group, i) => {
+    const last = i === MAX_TABS - 1;
+    // The final tab absorbs every remaining group, so a fifth group is folded in rather
+    // than dropped. Its sections keep their labels, since that tab now holds more than one.
+    const mine = last ? groups.slice(i) : [group];
+    // An unlabelled component after the lead inherits the area it sits inside, so a
+    // component the model forgot to label stays where the reader found it.
+    let carried = "";
+    const placed = list.map((s, idx) => {
+      if (idx < leadEnd) return s;
+      const g = typeof s.group === "string" && s.group ? s.group : carried;
+      carried = g || carried;
+      return { ...s, group: g };
+    });
+    const own = placed.filter((s) => mine.includes(s.group as string) && s.kind !== "finePrint");
+    out[`tab${i}Label`] = group;
+    // The tab IS the label for a single group, so its eyebrow would only repeat it. A
+    // folded tab keeps them, because it holds several.
+    const labelled = last && mine.length > 1 ? withGroupStarts(own) : own.map((s) => ({ ...s, group: "", groupStart: false }));
+    out[`tab${i}`] = [...(labelled as Record<string, unknown>[]), ...finePrint];
+  });
+  return out;
+}
+
+/**
+ * A record's sections as plain text, for embeddings and for anything that wants words
+ * rather than a document.
+ *
+ * DERIVED, never authored: the sections are the body, and this is a projection of them.
+ * The old order (markdown first, sections filed from it) is what made two representations
+ * of the same copy able to disagree.
+ */
+export function sectionsToText(sections: unknown): string {
+  if (!Array.isArray(sections)) return "";
+  const parts: string[] = [];
+  for (const raw of sections) {
+    const s = (raw ?? {}) as Record<string, any>;
+    if (s.heading) parts.push(`## ${s.heading}`);
+    if (s.body) parts.push(String(s.body));
+    for (const f of Array.isArray(s.facts) ? s.facts : [])
+      parts.push([f?.label, f?.value, f?.qualifier].filter(Boolean).join(": "));
+    for (const i of Array.isArray(s.items) ? s.items : [])
+      parts.push([i?.title, i?.body].filter(Boolean).join(" — ").replace(" — ", ": "));
+    if (Array.isArray(s.columns) && s.columns.length) parts.push(s.columns.join(" | "));
+    for (const row of Array.isArray(s.rows) ? s.rows : [])
+      if (Array.isArray(row)) parts.push(row.join(" | "));
+  }
+  return parts.filter(Boolean).join("\n\n");
+}

package/vendor/base/src/paths.ts

@@ -0,0 +1,180 @@
+/**
+ * WHERE THE CONTENT LIVES. One root, everything else derived from it.
+ *
+ * This used to be five environment variables over a repo-root walk that looked for a folder
+ * called `apps/unoverse`. That made the package repo-shaped: installed anywhere else, the
+ * walk finds nothing and every path silently comes out wrong, which surfaces as "the
+ * definition does not load" rather than as a path error.
+ *
+ * Now there is ONE knob, `UNOVERSE_HOME`, and the rest are folders inside it. A host that
+ * wants a different layout calls `setPaths()`; it does not need five more variables.
+ */
+
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { existsSync, renameSync } from "fs";
+
+/**
+ * Find the content home when nobody said.
+ *
+ * ANCHORED ON A MARKER, never on a depth. Counting `../` from this file's own location is
+ * what broke every path in the platform the last time this file moved: DESIGN_HOME landed one
+ * directory above the repo and every loader quietly found nothing.
+ */
+function findHome(): string {
+  const explicit = process.env.UNOVERSE_HOME;
+  if (explicit) return path.resolve(explicit);
+
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    // The in-repo home. Checked for `nodes` as well as the folder itself, so a stray
+    // directory of the same name elsewhere cannot claim it.
+    const candidate = path.join(dir, "apps/unoverse");
+    if (existsSync(path.join(candidate, "nodes"))) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Installed outside the monorepo with nothing configured. Returning a guess here is what
+  // produced the silent-wrong-path failures, so say so instead: every export below becomes
+  // a path under cwd, and anything reading them will fail somewhere obvious.
+  console.warn(
+    "[unoverse:base] UNOVERSE_HOME is not set and no apps/unoverse was found above this package. " +
+      "Falling back to the working directory; set UNOVERSE_HOME to the folder holding nodes/, design/ and prompts/.",
+  );
+  return process.cwd();
+}
+
+let HOME = findHome();
+
+/** Everything the runtime reads off disk, in one place. */
+export interface Paths {
+  /** Node manifests and node packages authored for this deployment. */
+  nodes: string;
+  /** Design data: components, templates, styles. */
+  design: string;
+  /** Authored agent skills (SKILL.md). */
+  skills: string;
+  /** Reusable prompt snippets. */
+  promptBlocks: string;
+  /** Where `npm install` puts legacy code node packages. */
+  plugins: string;
+  /** LEGACY: the pre-migration node package folders. Usually absent. */
+  packages: string;
+  /** LEGACY: the pre-migration marketplace folder. Usually absent. */
+  marketplace: string;
+}
+
+/**
+ * The design folder's on-disk name, renamed `rx` → `design` (2026-08-20).
+ *
+ * MIGRATE-ONCE, not dual-read: a root still holding the legacy `rx/` is renamed to
+ * `design/` the first time anything resolves it, and the platform knows ONE name from
+ * then on. Resolution doubling as migration is deliberate — every reader passes through
+ * here, so no entry point can forget to migrate, and no second code path survives to
+ * drift. If the rename is impossible (read-only mount), the warning says exactly what
+ * to do and resolution still returns `design/`: the failure is loud and immediate,
+ * never a silent read from a folder half the platform no longer knows about.
+ */
+export function designDir(root: string): string {
+  const design = path.join(root, "design");
+  const legacy = path.join(root, "rx");
+  if (!existsSync(design) && existsSync(legacy)) {
+    try {
+      renameSync(legacy, design);
+      console.warn(`[unoverse:base] migrated ${legacy} → ${design} (rx/ is now design/)`);
+    } catch (e) {
+      console.warn(
+        `[unoverse:base] could not rename ${legacy} → ${design} (${(e as Error).message}). ` +
+          `Rename it by hand; the platform reads design/ only.`,
+      );
+    }
+  }
+  return design;
+}
+
+function derive(home: string): Paths {
+  return {
+    nodes: path.join(home, "nodes"),
+    design: designDir(home),
+    skills: path.join(home, "prompts/skills"),
+    promptBlocks: path.join(home, "prompts/blocks"),
+    plugins: path.join(home, "plugins"),
+    // DELIBERATELY under the home, not at the repo root.
+    //
+    // `packages` used to mean "node packages" and now means "workspace libraries", and the
+    // old default pointed at the new folder. `discoverPlugins()` scans it for anything in
+    // the @unoverse-platform scope with an entry point, so it found THIS package and
+    // returned ["@unoverse-platform/base"] — the runtime being offered as a node.
+    packages: path.join(home, "packages"),
+    marketplace: path.join(home, "packages-marketplace"),
+  };
+}
+
+let paths: Paths = derive(HOME);
+
+/**
+ * Point the runtime at a different layout. For a host that does not lay content out this
+ * way, and the reason there is no environment variable per folder.
+ */
+export function setPaths(next: Partial<Paths> & { home?: string }): void {
+  if (next.home) {
+    HOME = path.resolve(next.home);
+    paths = derive(HOME);
+  }
+  const { home: _ignored, ...rest } = next;
+  paths = { ...paths, ...rest };
+}
+
+/** The content home in force. */
+export function unoverseHome(): string {
+  return HOME;
+}
+
+/** Everything, as one object. Prefer this over the individual exports below. */
+export function getPaths(): Paths {
+  return paths;
+}
+
+// Named exports, kept because the tree already reads them. They are RESOLVED ONCE at import,
+// so a host calling setPaths() must do it before anything else imports this module.
+export const NODES_HOME = paths.nodes;
+export const DESIGN_HOME = paths.design;
+export const SKILLS_HOME = paths.skills;
+export const PROMPT_BLOCKS_HOME = paths.promptBlocks;
+/**
+ * Where INSTALLED items are written so the loaders can read them (items/hydrate.ts).
+ *
+ * A SEPARATE ROOT, never inside the design tree. In the monorepo `DESIGN_HOME` is somebody's authoring
+ * tree, and hydrating a database into it would overwrite work in progress. Keeping it
+ * apart is also what makes the precedence rule enforceable: the on-disk tiers are searched
+ * first and an installed row can only ever fill a gap, never replace what the platform
+ * ships.
+ *
+ * Rebuilt whole on every hydrate, so nothing here is worth backing up and editing it by
+ * hand achieves nothing.
+ */
+export const INSTALLED_HOME = process.env.UNOVERSE_INSTALLED_HOME?.trim() || path.join(HOME, ".installed");
+
+/**
+ * `UNOVERSE_DATABASE_ONLY=1` — behave like a deployed universe on a developer's machine.
+ *
+ * A server holds no design tree, no prompts and no node manifests, so everything it serves comes
+ * from its database. In the monorepo those folders are full, they are searched first, and
+ * they win — which is correct for authoring and means the production path is never
+ * exercised until it is deployed. This turns the on-disk tiers off so the database is the
+ * only source, exactly as it is in production.
+ *
+ * A TEST SWITCH, NOT A MODE. It changes nothing about how anything is stored or resolved,
+ * only which tiers are consulted, so a bug found with it on is a real bug rather than an
+ * artefact of a second code path. It is read from the environment and never written to,
+ * and a deployed universe does not set it: there, the folders are empty anyway.
+ */
+export function databaseOnly(): boolean {
+  const v = process.env.UNOVERSE_DATABASE_ONLY?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+export const PLUGINS_DIR = paths.plugins;
+export const PACKAGES_PATH = paths.packages;
+export const MARKETPLACE_PATH = paths.marketplace;

package/vendor/base/src/platform/audioManager.ts

@@ -0,0 +1,100 @@
+/**
+ * Distributed Audio Manager
+ * Provides the audio WebSocket manager interface voice plugins (aws-nova /
+ * openai-realtime) use. Live audio now streams DIRECTLY from this process to the
+ * channel SDK over the in-process `/ws/gravity` WS (UNOVERSE_MCP_APP_PROTOCOL
+ * §5a-refined) — NOT relayed through the legacy gateway. Component publishing
+ * (publishToClient / SERVICE_PUBLISH) still goes to the gateway and is untouched.
+ */
+
+import { clientTransport } from "./clientTransport.js";
+
+export interface AudioWebSocketManager {
+  setAudioDataHandler(handler: (conversationId: string, audioData: ArrayBuffer, metadata?: any) => Promise<void>): void;
+  setControlMessageHandler(handler: (conversationId: string, message: any) => Promise<void>): void;
+  startAudioSession(conversationId: string, novaSessionId?: string): void;
+  endAudioSession(conversationId: string): void;
+  isConnected(conversationId: string): boolean;
+  sendAudio(conversationId: string, audioData: Buffer | ArrayBuffer): boolean;
+  sendControl(conversationId: string, message: Record<string, any>): boolean;
+}
+
+class DistributedAudioManager implements AudioWebSocketManager {
+  private audioSessions: Map<string, { novaSessionId?: string; active: boolean }> = new Map();
+
+  /**
+   * Set audio data handler (called by WebSocketAudioSubscriber)
+   */
+  setAudioDataHandler(
+    handler: (conversationId: string, audioData: ArrayBuffer, metadata?: any) => Promise<void>
+  ): void {
+    clientTransport().setAudioDataHandler(async (conversationId, audioData) => {
+      const session = this.audioSessions.get(conversationId);
+      if (session?.active) {
+        await handler(conversationId, audioData, { novaSessionId: session.novaSessionId });
+      }
+    });
+    // Wiring, not news.
+  }
+
+  /**
+   * Set control message handler (called by WebSocketAudioSubscriber)
+   */
+  setControlMessageHandler(handler: (conversationId: string, message: any) => Promise<void>): void {
+    clientTransport().setAudioControlHandler(handler);
+    // Wiring, not news.
+  }
+
+  /**
+   * Start audio session
+   */
+  startAudioSession(conversationId: string, novaSessionId?: string): void {
+    this.audioSessions.set(conversationId, { novaSessionId, active: true });
+    console.log(`[DistributedAudioManager] Audio session started: ${conversationId}`);
+  }
+
+  /**
+   * End audio session
+   */
+  endAudioSession(conversationId: string): void {
+    const session = this.audioSessions.get(conversationId);
+    if (session) {
+      session.active = false;
+    }
+    console.log(`[DistributedAudioManager] Audio session ended: ${conversationId}`);
+  }
+
+  /**
+   * Check if connected (always true if WebSocket is connected)
+   */
+  isConnected(conversationId: string): boolean {
+    return this.audioSessions.has(conversationId);
+  }
+
+  /**
+   * Send audio to client via server
+   */
+  sendAudio(conversationId: string, audioData: Buffer | ArrayBuffer): boolean {
+    return clientTransport().sendAudioToClient(conversationId, audioData);
+  }
+
+  /**
+   * Send control/state message to client via server
+   */
+  sendControl(conversationId: string, message: Record<string, any>): boolean {
+    if (message.type === "AUDIO_STATE" || message.state) {
+      return clientTransport().sendAudioStateToClient(conversationId, message.state || message.type, message.metadata);
+    }
+    return false;
+  }
+}
+
+// Singleton instance
+let distributedAudioManager: DistributedAudioManager | null = null;
+
+export function getDistributedAudioManager(): AudioWebSocketManager {
+  if (!distributedAudioManager) {
+    distributedAudioManager = new DistributedAudioManager();
+  }
+  return distributedAudioManager;
+}