perf(tools): generate serializable tool metadata artifacts

Adds `scripts/sync-tool-metadata.ts`, which projects the executable tool
registry down to the data half nobody needs a closure for, plus typed accessors
over the result. No consumer is rewired yet — that is the next PR.

`@/tools/registry` is a ~9,000-line barrel over 4,366 tools. Each `ToolConfig`
mixes plain data (`params`, `outputs`, `name`) with closures (`request.headers`,
`transformResponse`, `directExecution`, `postProcess`), and those closures reach
every integration's SDK client and parser — which is why reaching the barrel
costs ~4,700 modules. Every client-reachable caller was audited: none of them
need a closure. They need `outputs`, `params`, or an existence check.

Two artifacts, not one. `outputs` is ~4 MB of the ~8 MB and has a single
consumer, so it is emitted separately and exposed from its own module; callers
needing only params never load it.

The data is a JSON string parsed at runtime rather than an imported `.json` or
an object literal. That is not stylistic — with `resolveJsonModule` (enabled
repo-wide) a `.json` import makes TypeScript infer a literal type for all 4,366
entries:

  tsc --noEmit, baseline                12.6s
  tsc --noEmit, with `.json` imports    8m07s   (38x)
  tsc --noEmit, with string literals    12.0s

An ambient `declare module` does not short-circuit it (measured: 8m18s), and an
object literal is the same inference work. A single string literal is one cheap
token for the compiler and the bundler, and `JSON.parse` beats evaluating the
equivalent literal at runtime.

The generator refuses to emit any function value, so shipping executable config
to the client fails loudly instead of silently. `hosting` and `schemaEnrichment`
are excluded on those grounds — both hold functions and are server-only.

Also strips empty param entries: the registry has one (`stt_deepgram_v2`, an
`undefined`) which crashes callers that read `param.type` while iterating.
`JSON.stringify` drops `undefined` on its own, so the guard is there for an
explicit `null` — which serializes faithfully and would reach consumers — and to
warn either way.

Wires `tool-metadata:check` into CI alongside the other generated-contract
gates, and ignores the generated directory in biome (it exceeds the 1 MB limit
and was being skipped with a notice on every commit).

Adds a `tool-registry-boundary` skill covering which module to import, the three
non-obvious properties of the artifacts, and how to verify an edge is actually
cut — the canvas route reaches the registry through four redundant paths, so
cutting one alone moves the module count by ~1.

Author: waleedlatif1

.agents/skills/tool-registry-boundary/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: tool-registry-boundary
+description: Keep the executable tool registry out of client-reachable module graphs — when to read `@/tools/metadata` instead of `getTool`, how to measure whether an import edge pulls the registry, and how to regenerate the metadata artifacts. Use when touching `apps/sim/tools/registry.ts`, `tools/utils.ts`, `tools/params.ts`, or anything that calls `getTool`.
+---
+
+# Tool Registry Boundary Skill
+
+You keep the 4,300-tool executable registry out of module graphs that don't execute tools.
+
+## The rule
+
+> Client-reachable code reads tool **metadata**. Only code that actually executes a tool imports the **registry**.
+
+`@/tools/registry` is a ~9,000-line barrel importing every tool. Each `ToolConfig` mixes plain data (`params`, `outputs`, `name`) with closures — `request.url`, `request.headers`, `transformResponse`, `directExecution`, `postProcess`. Those closures reach the SDK clients, API helpers and parsers each integration needs, and that is what makes the barrel expensive: reaching it costs ~4,700 additional modules.
+
+`getTool()` returns the whole `ToolConfig`, so a single `getTool` import anywhere in a client-reachable file drags all of it in.
+
+## Which module to import
+
+| you need | import | notes |
+| --- | --- | --- |
+| whether a tool id exists | `hasToolMetadata` from `@/tools/metadata` | |
+| a tool's params | `getToolParams` / `getToolMetadata` from `@/tools/metadata` | |
+| a tool's declared outputs | `getToolOutputsMetadata` from `@/tools/metadata-outputs` | separate module on purpose — see below |
+| every tool id | `getToolIds` from `@/tools/metadata` | |
+| to **execute** a tool | `getTool` from `@/tools/utils`, or `@/tools/utils.server` | server paths only |
+
+Outputs live in their own module because they are roughly two thirds of the generated data and have a single consumer. Importing `@/tools/metadata` must never pull them — do not "helpfully" re-export one from the other.
+
+## The generated artifacts
+
+`apps/sim/tools/generated/tool-metadata.ts` and `tool-outputs.ts` are produced by `scripts/sync-tool-metadata.ts`:
+
+```bash
+bun run tool-metadata:generate   # after adding/changing a tool
+bun run tool-metadata:check      # what CI runs; fails if stale
+```
+
+Never hand-edit them. If you add a tool or change a tool's `params`/`outputs`, regenerate and commit the result, or CI fails.
+
+Three non-obvious properties, each of which was measured and is easy to undo by accident:
+
+- **The data is a JSON string parsed at runtime, not an imported `.json` and not an object literal.** With `resolveJsonModule` (which this repo enables), a `.json` import makes TypeScript infer a literal type for all 4,300+ entries and takes `tsc --noEmit` from **12.6s to 8m07s** — a 38x regression. An ambient `declare module` does *not* short-circuit it, and an object literal costs the same. A single string literal is one cheap token for both the compiler and the bundler, and `JSON.parse` beats evaluating the equivalent literal at runtime. Do not "clean this up" into a `.json` import.
+- **The generator refuses to emit function values.** If you add a field to `METADATA_FIELDS` that contains a closure, generation fails loudly rather than shipping executable config to the client. `hosting` and `schemaEnrichment` are excluded for exactly this reason (`hosting.enabled`, `pricing`, and `enrichSchema` are functions) — they are server-only.
+- **Empty param entries are stripped.** The registry contains one (`stt_deepgram_v2`), which crashes callers that read `param.type` while iterating.
+
+## How to verify an edge actually got cut
+
+Do not eyeball imports — the registry is reached through several redundant paths, so cutting one buys nothing while another survives. Walk the graph:
+
+1. From the entry you care about, follow `import` and `export … from` (skipping `import type`), resolving `@/` against `apps/sim`.
+2. Check whether `apps/sim/tools/registry.ts` is in the reachable set, and print the parent chain if it is.
+3. Compare the reachable module count before and after.
+
+Reference points measured on this repo:
+
+| entry | modules |
+| --- | --- |
+| `tools/registry.ts` reachable | ~4,900 |
+| `tools/merge-params.ts` (leaf) | 2 |
+| `providers/utils.ts` after cutting its `params` edge | 22 |
+| `app/workspace/[workspaceId]/w/page.tsx` (canvas) | 6,591, of which 4,689 are the registry |
+
+The canvas route reaches the registry through **four** redundant edges — `providers/utils` (via `tools/params`), `lib/workflows/blocks/block-outputs`, `lib/workflows/sanitization/validation`, and `serializer/index`. Cutting any one alone moves the module count by ~1. They must all be cut before anything improves; measure the route, not the file you edited.
+
+## When adding a new caller
+
+Ask what the caller does with the config. If it reads `params`, `outputs`, `name`, `description` or just checks existence, it belongs on `@/tools/metadata` — no exceptions, even on a path you believe is server-only today, because a future client import will silently re-attach the registry to the graph.
+
+If it genuinely executes — builds a request, transforms a response, runs `directExecution` — use `getTool`, and keep that file off client-reachable paths.

.claude/commands/tool-registry-boundary.md

@@ -0,0 +1,69 @@
+---
+description: Keep the executable tool registry out of client-reachable module graphs — when to read `@/tools/metadata` instead of `getTool`, how to measure whether an import edge pulls the registry, and how to regenerate the metadata artifacts. Use when touching `apps/sim/tools/registry.ts`, `tools/utils.ts`, `tools/params.ts`, or anything that calls `getTool`.
+---
+
+# Tool Registry Boundary Skill
+
+You keep the 4,300-tool executable registry out of module graphs that don't execute tools.
+
+## The rule
+
+> Client-reachable code reads tool **metadata**. Only code that actually executes a tool imports the **registry**.
+
+`@/tools/registry` is a ~9,000-line barrel importing every tool. Each `ToolConfig` mixes plain data (`params`, `outputs`, `name`) with closures — `request.url`, `request.headers`, `transformResponse`, `directExecution`, `postProcess`. Those closures reach the SDK clients, API helpers and parsers each integration needs, and that is what makes the barrel expensive: reaching it costs ~4,700 additional modules.
+
+`getTool()` returns the whole `ToolConfig`, so a single `getTool` import anywhere in a client-reachable file drags all of it in.
+
+## Which module to import
+
+| you need | import | notes |
+| --- | --- | --- |
+| whether a tool id exists | `hasToolMetadata` from `@/tools/metadata` | |
+| a tool's params | `getToolParams` / `getToolMetadata` from `@/tools/metadata` | |
+| a tool's declared outputs | `getToolOutputsMetadata` from `@/tools/metadata-outputs` | separate module on purpose — see below |
+| every tool id | `getToolIds` from `@/tools/metadata` | |
+| to **execute** a tool | `getTool` from `@/tools/utils`, or `@/tools/utils.server` | server paths only |
+
+Outputs live in their own module because they are roughly two thirds of the generated data and have a single consumer. Importing `@/tools/metadata` must never pull them — do not "helpfully" re-export one from the other.
+
+## The generated artifacts
+
+`apps/sim/tools/generated/tool-metadata.ts` and `tool-outputs.ts` are produced by `scripts/sync-tool-metadata.ts`:
+
+```bash
+bun run tool-metadata:generate   # after adding/changing a tool
+bun run tool-metadata:check      # what CI runs; fails if stale
+```
+
+Never hand-edit them. If you add a tool or change a tool's `params`/`outputs`, regenerate and commit the result, or CI fails.
+
+Three non-obvious properties, each of which was measured and is easy to undo by accident:
+
+- **The data is a JSON string parsed at runtime, not an imported `.json` and not an object literal.** With `resolveJsonModule` (which this repo enables), a `.json` import makes TypeScript infer a literal type for all 4,300+ entries and takes `tsc --noEmit` from **12.6s to 8m07s** — a 38x regression. An ambient `declare module` does *not* short-circuit it, and an object literal costs the same. A single string literal is one cheap token for both the compiler and the bundler, and `JSON.parse` beats evaluating the equivalent literal at runtime. Do not "clean this up" into a `.json` import.
+- **The generator refuses to emit function values.** If you add a field to `METADATA_FIELDS` that contains a closure, generation fails loudly rather than shipping executable config to the client. `hosting` and `schemaEnrichment` are excluded for exactly this reason (`hosting.enabled`, `pricing`, and `enrichSchema` are functions) — they are server-only.
+- **Empty param entries are stripped.** The registry contains one (`stt_deepgram_v2`), which crashes callers that read `param.type` while iterating.
+
+## How to verify an edge actually got cut
+
+Do not eyeball imports — the registry is reached through several redundant paths, so cutting one buys nothing while another survives. Walk the graph:
+
+1. From the entry you care about, follow `import` and `export … from` (skipping `import type`), resolving `@/` against `apps/sim`.
+2. Check whether `apps/sim/tools/registry.ts` is in the reachable set, and print the parent chain if it is.
+3. Compare the reachable module count before and after.
+
+Reference points measured on this repo:
+
+| entry | modules |
+| --- | --- |
+| `tools/registry.ts` reachable | ~4,900 |
+| `tools/merge-params.ts` (leaf) | 2 |
+| `providers/utils.ts` after cutting its `params` edge | 22 |
+| `app/workspace/[workspaceId]/w/page.tsx` (canvas) | 6,591, of which 4,689 are the registry |
+
+The canvas route reaches the registry through **four** redundant edges — `providers/utils` (via `tools/params`), `lib/workflows/blocks/block-outputs`, `lib/workflows/sanitization/validation`, and `serializer/index`. Cutting any one alone moves the module count by ~1. They must all be cut before anything improves; measure the route, not the file you edited.
+
+## When adding a new caller
+
+Ask what the caller does with the config. If it reads `params`, `outputs`, `name`, `description` or just checks existence, it belongs on `@/tools/metadata` — no exceptions, even on a path you believe is server-only today, because a future client import will silently re-attach the registry to the graph.
+
+If it genuinely executes — builds a request, transforms a response, runs `directExecution` — use `getTool`, and keep that file off client-reachable paths.

.cursor/commands/tool-registry-boundary.md

@@ -0,0 +1,65 @@
+# Tool Registry Boundary Skill
+
+You keep the 4,300-tool executable registry out of module graphs that don't execute tools.
+
+## The rule
+
+> Client-reachable code reads tool **metadata**. Only code that actually executes a tool imports the **registry**.
+
+`@/tools/registry` is a ~9,000-line barrel importing every tool. Each `ToolConfig` mixes plain data (`params`, `outputs`, `name`) with closures — `request.url`, `request.headers`, `transformResponse`, `directExecution`, `postProcess`. Those closures reach the SDK clients, API helpers and parsers each integration needs, and that is what makes the barrel expensive: reaching it costs ~4,700 additional modules.
+
+`getTool()` returns the whole `ToolConfig`, so a single `getTool` import anywhere in a client-reachable file drags all of it in.
+
+## Which module to import
+
+| you need | import | notes |
+| --- | --- | --- |
+| whether a tool id exists | `hasToolMetadata` from `@/tools/metadata` | |
+| a tool's params | `getToolParams` / `getToolMetadata` from `@/tools/metadata` | |
+| a tool's declared outputs | `getToolOutputsMetadata` from `@/tools/metadata-outputs` | separate module on purpose — see below |
+| every tool id | `getToolIds` from `@/tools/metadata` | |
+| to **execute** a tool | `getTool` from `@/tools/utils`, or `@/tools/utils.server` | server paths only |
+
+Outputs live in their own module because they are roughly two thirds of the generated data and have a single consumer. Importing `@/tools/metadata` must never pull them — do not "helpfully" re-export one from the other.
+
+## The generated artifacts
+
+`apps/sim/tools/generated/tool-metadata.ts` and `tool-outputs.ts` are produced by `scripts/sync-tool-metadata.ts`:
+
+```bash
+bun run tool-metadata:generate   # after adding/changing a tool
+bun run tool-metadata:check      # what CI runs; fails if stale
+```
+
+Never hand-edit them. If you add a tool or change a tool's `params`/`outputs`, regenerate and commit the result, or CI fails.
+
+Three non-obvious properties, each of which was measured and is easy to undo by accident:
+
+- **The data is a JSON string parsed at runtime, not an imported `.json` and not an object literal.** With `resolveJsonModule` (which this repo enables), a `.json` import makes TypeScript infer a literal type for all 4,300+ entries and takes `tsc --noEmit` from **12.6s to 8m07s** — a 38x regression. An ambient `declare module` does *not* short-circuit it, and an object literal costs the same. A single string literal is one cheap token for both the compiler and the bundler, and `JSON.parse` beats evaluating the equivalent literal at runtime. Do not "clean this up" into a `.json` import.
+- **The generator refuses to emit function values.** If you add a field to `METADATA_FIELDS` that contains a closure, generation fails loudly rather than shipping executable config to the client. `hosting` and `schemaEnrichment` are excluded for exactly this reason (`hosting.enabled`, `pricing`, and `enrichSchema` are functions) — they are server-only.
+- **Empty param entries are stripped.** The registry contains one (`stt_deepgram_v2`), which crashes callers that read `param.type` while iterating.
+
+## How to verify an edge actually got cut
+
+Do not eyeball imports — the registry is reached through several redundant paths, so cutting one buys nothing while another survives. Walk the graph:
+
+1. From the entry you care about, follow `import` and `export … from` (skipping `import type`), resolving `@/` against `apps/sim`.
+2. Check whether `apps/sim/tools/registry.ts` is in the reachable set, and print the parent chain if it is.
+3. Compare the reachable module count before and after.
+
+Reference points measured on this repo:
+
+| entry | modules |
+| --- | --- |
+| `tools/registry.ts` reachable | ~4,900 |
+| `tools/merge-params.ts` (leaf) | 2 |
+| `providers/utils.ts` after cutting its `params` edge | 22 |
+| `app/workspace/[workspaceId]/w/page.tsx` (canvas) | 6,591, of which 4,689 are the registry |
+
+The canvas route reaches the registry through **four** redundant edges — `providers/utils` (via `tools/params`), `lib/workflows/blocks/block-outputs`, `lib/workflows/sanitization/validation`, and `serializer/index`. Cutting any one alone moves the module count by ~1. They must all be cut before anything improves; measure the route, not the file you edited.
+
+## When adding a new caller
+
+Ask what the caller does with the config. If it reads `params`, `outputs`, `name`, `description` or just checks existence, it belongs on `@/tools/metadata` — no exceptions, even on a path you believe is server-only today, because a future client import will silently re-attach the registry to the graph.
+
+If it genuinely executes — builds a request, transforms a response, runs `directExecution` — use `getTool`, and keep that file off client-reachable paths.

.github/workflows/test-build.yml

@@ -153,6 +153,9 @@ jobs:
       - name: Verify realtime prune graph
         run: bun run check:realtime-prune
 
+      - name: Verify generated tool metadata is in sync
+        run: bun run tool-metadata:check
+
       - name: Verify skill projections are in sync
         run: bun run skills:check
 

apps/sim/tools/generated/tool-metadata.ts

@@ -0,0 +1,28 @@
+import rawOutputs from '@/tools/generated/tool-outputs'
+import type { ToolConfig } from '@/tools/types'
+
+/**
+ * Declared output shapes for built-in tools, read without importing the
+ * executable registry. See `@/tools/metadata` for the rationale.
+ *
+ * Kept apart from the rest of the metadata because outputs are roughly two
+ * thirds of the generated data and only block-output inference consumes them —
+ * callers that need params or an existence check should import `@/tools/metadata`
+ * and never load this module.
+ *
+ * The backing data is generated by `scripts/sync-tool-metadata.ts` and verified
+ * in CI by `bun run tool-metadata:check`. Never hand-edit it.
+ */
+type ToolOutputs = NonNullable<ToolConfig['outputs']>
+
+/**
+ * Annotated rather than inferred: letting TypeScript infer a literal type for a
+ * 4 MB JSON import makes every downstream file that touches it dramatically more
+ * expensive to typecheck.
+ */
+const outputs: Record<string, ToolOutputs> = rawOutputs as Record<string, ToolOutputs>
+
+/** Declared outputs for a built-in tool, or `undefined` if it declares none. */
+export function getToolOutputsMetadata(toolId: string): ToolOutputs | undefined {
+  return outputs[toolId]
+}

apps/sim/tools/generated/tool-outputs.ts

@@ -0,0 +1,66 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { getToolIds, getToolMetadata, getToolParams, hasToolMetadata } from '@/tools/metadata'
+import { getToolOutputsMetadata } from '@/tools/metadata-outputs'
+
+/**
+ * Guards the properties the generated artifacts are relied on for. The
+ * `tool-metadata:check` script guards that they are in sync with the registry;
+ * these guard that what they contain is usable.
+ */
+describe('generated tool metadata', () => {
+  it('covers the whole registry', () => {
+    expect(getToolIds().length).toBeGreaterThan(4000)
+  })
+
+  it('resolves a known tool with its params', () => {
+    const gmail = getToolMetadata('gmail_send')
+    expect(gmail?.id).toBe('gmail_send')
+    expect(Object.keys(gmail?.params ?? {})).toContain('to')
+  })
+
+  it('reports unknown tools as absent without throwing', () => {
+    expect(hasToolMetadata('definitely_not_a_tool')).toBe(false)
+    expect(getToolMetadata('definitely_not_a_tool')).toBeUndefined()
+    expect(getToolParams('definitely_not_a_tool')).toBeUndefined()
+    expect(getToolOutputsMetadata('definitely_not_a_tool')).toBeUndefined()
+  })
+
+  it('resolves declared outputs for a known tool', () => {
+    expect(getToolOutputsMetadata('gmail_send')).toBeDefined()
+  })
+
+  /**
+   * The registry contains a null param entry (`stt_deepgram_v2`), which crashes
+   * any consumer that iterates params unguarded. The generator strips those, so
+   * consumers may iterate freely.
+   */
+  it('contains no null param entries', () => {
+    for (const id of getToolIds()) {
+      for (const [paramId, config] of Object.entries(getToolParams(id) ?? {})) {
+        expect(config, `${id}.${paramId} is empty`).not.toBeNull()
+        expect(config, `${id}.${paramId} is empty`).toBeDefined()
+      }
+    }
+  })
+
+  /**
+   * The whole point of the artifacts: they carry no executable config, so
+   * importing them cannot pull the tool implementations into a module graph.
+   */
+  it('contains no function values', () => {
+    for (const id of getToolIds()) {
+      const metadata = getToolMetadata(id)
+      for (const [key, value] of Object.entries(metadata ?? {})) {
+        expect(typeof value, `${id}.${key} is a function`).not.toBe('function')
+      }
+      for (const [paramId, config] of Object.entries(metadata?.params ?? {})) {
+        for (const [key, value] of Object.entries(config ?? {})) {
+          expect(typeof value, `${id}.params.${paramId}.${key} is a function`).not.toBe('function')
+        }
+      }
+    }
+  })
+})