feat(catalog): browser-safe model-catalogue subpath (#186)

./runtime is a server barrel — importing any VALUE from it in client
code ships @tangle-network/agent-runtime (node:util, child_process)
into the route bundle, which throws on module load. This broke the
legal-agent chat route and the tax-agent home composer. ./catalog
re-exports only the pure catalogue pipeline; a source-graph test
fails loud if the subpath ever reaches a node builtin.

Author: drewstone

package.json

@@ -58,6 +58,11 @@
       "import": "./dist/runtime/index.js",
       "default": "./dist/runtime/index.js"
     },
+    "./catalog": {
+      "types": "./dist/catalog/index.d.ts",
+      "import": "./dist/catalog/index.js",
+      "default": "./dist/catalog/index.js"
+    },
     "./eval": {
       "types": "./dist/eval/index.d.ts",
       "import": "./dist/eval/index.js",

src/catalog/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser-safe model-catalogue subpath.
+ *
+ * `./runtime` is a SERVER barrel: alongside the catalogue it re-exports
+ * `createAgentRuntime`/`runAppToolLoop`, which import
+ * `@tangle-network/agent-runtime` (node:util, child_process). Any client
+ * component that imports a `/runtime` VALUE ships Node-only code into its
+ * route bundle and the module throws on load — this broke the chat route on
+ * legal-agent (#256) and the home composer on tax-agent (#372).
+ *
+ * This subpath re-exports ONLY the pure catalogue pipeline (no Node imports,
+ * no agent-runtime) so pickers and client hooks have a safe import target.
+ * Server code may keep importing from `./runtime`; the two share one source.
+ */
+export {
+  buildCatalog,
+  fetchModelCatalog,
+  normalizeModelId,
+  __resetCatalogCache,
+  type CatalogModel,
+  type ModelCatalog,
+  type RouterModel,
+} from '../runtime/model-catalog'

tests/catalog-browser-safe.test.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * `./catalog` is the browser-safe catalogue subpath: client components import
+ * `buildCatalog`/`CatalogModel` from it. If anything reachable from it gains a
+ * Node-only or agent-runtime import, every consumer's client bundle crashes on
+ * module load (legal-agent #256, tax-agent #372). Walk the source import graph
+ * and fail loud on the first unsafe edge.
+ */
+const FORBIDDEN = [/^node:/, /^@tangle-network\/agent-runtime/, /^child_process$/, /^fs$/, /^util$/]
+
+function localImports(file: string): string[] {
+  const src = readFileSync(file, 'utf8')
+  return [...src.matchAll(/from\s+['"]([^'"]+)['"]/g)].flatMap((m) => (m[1] ? [m[1]] : []))
+}
+
+describe('catalog subpath browser-safety', () => {
+  it('reaches no node builtins or agent-runtime imports', () => {
+    const seen = new Set<string>()
+    const queue = [resolve(__dirname, '../src/catalog/index.ts')]
+    while (queue.length) {
+      const file = queue.pop()!
+      if (seen.has(file)) continue
+      seen.add(file)
+      for (const spec of localImports(file)) {
+        for (const bad of FORBIDDEN) {
+          expect(spec, `${file} imports forbidden "${spec}"`).not.toMatch(bad)
+        }
+        if (spec.startsWith('.')) {
+          const base = resolve(dirname(file), spec)
+          queue.push(base.endsWith('.ts') ? base : `${base}.ts`)
+        }
+      }
+    }
+    // sanity: the walk actually traversed into the shared pipeline
+    expect([...seen].some((f) => f.endsWith('runtime/model-catalog.ts'))).toBe(true)
+  })
+})

tsup.config.ts

@@ -6,6 +6,7 @@ export default defineConfig({
     'tools/index': 'src/tools/index.ts',
     'tangle/index': 'src/tangle/index.ts',
     'runtime/index': 'src/runtime/index.ts',
+    'catalog/index': 'src/catalog/index.ts',
     'eval/index': 'src/eval/index.ts',
     'eval-campaign/index': 'src/eval-campaign/index.ts',
     'knowledge/index': 'src/knowledge/index.ts',