improvement(tools): route internal API calls through one declarative primitive

Calls to Sim's own API were identified by inspecting the resolved URL string for
an /api/ prefix, in two separate transports. Both now take an internalRoute
template: the route comes from a source literal, interpolated ids are encoded,
and query params go through withQuery. Static config strings stay as they are.

Author: waleedlatif1

.agents/skills/add-integration/SKILL.md

@@ -872,7 +872,12 @@ export const {service}UploadTool: ToolConfig<Params, Response> = {
     fileContent: { type: 'string', required: false, visibility: 'hidden' }, // Legacy
   },
   request: {
-    url: '/api/tools/{service}/upload',  // Internal route
+    // Internal route. A static string is a source literal, so the transport trusts it. When the
+    // path is dynamic, use `internalRoute` from '@/tools/internal-route' instead of a template
+    // string — a builder's plain `/api/...` string is treated as external, because a caller- or
+    // model-supplied param can produce one:
+    //   url: (params) => internalRoute`/api/tools/{service}/upload/${params.folderId}`
+    url: '/api/tools/{service}/upload',
     method: 'POST',
     body: (params) => ({
       accessToken: params.accessToken,

.agents/skills/add-tools/SKILL.md

@@ -145,6 +145,37 @@ export const {serviceName}{Action}Tool: ToolConfig<
 - Always explicitly set `required: true` or `required: false`
 - Optional params should have `required: false`
 
+## Internal Routes (calling Sim's own API)
+
+Most tools call a third-party service and `request.url` returns an absolute `https://...` URL. A
+tool that instead calls Sim's own API — a `/api/tools/{service}/{action}` proxy route, or a platform
+route like `/api/table/...` — must SAY SO, because the transport resolves those against the internal
+base URL and signs them with an internal token for the executing user.
+
+That declaration comes from the tool's source, never from the resolved string: a `user-or-llm` param
+can make any tool emit `/api/...` (the HTTP Request tool passes its `url` through verbatim, and a
+self-hosted integration with a blank host param collapses `${host}/api/v2/x` to `/api/v2/x`).
+
+```typescript
+import { internalRoute } from '@/tools/internal-route'
+
+// ✓ Static route — a source literal no param can influence
+url: '/api/tools/{service}/{action}',
+
+// ✓ Dynamic route — branded, and every interpolated id is percent-encoded for you
+url: (params) => internalRoute`/api/table/${params.tableId}/rows`,
+
+// ✓ Query params via withQuery (accepts an object or URLSearchParams; skips undefined/null)
+url: (params) => internalRoute`/api/logs`.withQuery({ workspaceId, limit: params.limit }),
+
+// ✗ Treated as EXTERNAL and will fail — a builder's plain string carries no provenance
+url: (params) => `/api/table/${params.tableId}/rows`,
+```
+
+`internalRoute` throws on a path outside `/api/` and on a query string inside the template. Never
+write `encodeURIComponent` inside the template — the tag already encodes each `${...}`, so doing it
+yourself double-encodes the value.
+
 ## Resolved Secrets and Provenance Boundaries
 
 - Leave ordinary external API inputs and third-party results unchanged. Add provenance handling only

.agents/skills/validate-integration/SKILL.md

@@ -71,6 +71,15 @@ For **every** tool file, check:
 - [ ] Tool `description` is a concise one-liner describing what it does
 - [ ] Tool `version` is set (`'1.0.0'` or `'2.0.0'` for V2)
 
+### Request URL
+- [ ] A tool calling a third-party service returns an ABSOLUTE `https://...` URL
+- [ ] A tool calling Sim's own API declares it: a static `/api/...` string, or `internalRoute` from
+      `@/tools/internal-route` when the path is dynamic (query params via `.withQuery({...})`)
+- [ ] No builder returns a bare `` `/api/...` `` template string — that is treated as external and
+      will fail, because a `user-or-llm` param can produce the same string
+- [ ] No `encodeURIComponent` inside an `internalRoute` template (the tag already encodes, so this
+      double-encodes the value)
+
 ### Params
 - [ ] All required API params are marked `required: true`
 - [ ] All optional API params are marked `required: false`

.claude/commands/add-integration.md

@@ -871,7 +871,12 @@ export const {service}UploadTool: ToolConfig<Params, Response> = {
     fileContent: { type: 'string', required: false, visibility: 'hidden' }, // Legacy
   },
   request: {
-    url: '/api/tools/{service}/upload',  // Internal route
+    // Internal route. A static string is a source literal, so the transport trusts it. When the
+    // path is dynamic, use `internalRoute` from '@/tools/internal-route' instead of a template
+    // string — a builder's plain `/api/...` string is treated as external, because a caller- or
+    // model-supplied param can produce one:
+    //   url: (params) => internalRoute`/api/tools/{service}/upload/${params.folderId}`
+    url: '/api/tools/{service}/upload',
     method: 'POST',
     body: (params) => ({
       accessToken: params.accessToken,

.claude/commands/add-tools.md

@@ -144,6 +144,37 @@ export const {serviceName}{Action}Tool: ToolConfig<
 - Always explicitly set `required: true` or `required: false`
 - Optional params should have `required: false`
 
+## Internal Routes (calling Sim's own API)
+
+Most tools call a third-party service and `request.url` returns an absolute `https://...` URL. A
+tool that instead calls Sim's own API — a `/api/tools/{service}/{action}` proxy route, or a platform
+route like `/api/table/...` — must SAY SO, because the transport resolves those against the internal
+base URL and signs them with an internal token for the executing user.
+
+That declaration comes from the tool's source, never from the resolved string: a `user-or-llm` param
+can make any tool emit `/api/...` (the HTTP Request tool passes its `url` through verbatim, and a
+self-hosted integration with a blank host param collapses `${host}/api/v2/x` to `/api/v2/x`).
+
+```typescript
+import { internalRoute } from '@/tools/internal-route'
+
+// ✓ Static route — a source literal no param can influence
+url: '/api/tools/{service}/{action}',
+
+// ✓ Dynamic route — branded, and every interpolated id is percent-encoded for you
+url: (params) => internalRoute`/api/table/${params.tableId}/rows`,
+
+// ✓ Query params via withQuery (accepts an object or URLSearchParams; skips undefined/null)
+url: (params) => internalRoute`/api/logs`.withQuery({ workspaceId, limit: params.limit }),
+
+// ✗ Treated as EXTERNAL and will fail — a builder's plain string carries no provenance
+url: (params) => `/api/table/${params.tableId}/rows`,
+```
+
+`internalRoute` throws on a path outside `/api/` and on a query string inside the template. Never
+write `encodeURIComponent` inside the template — the tag already encodes each `${...}`, so doing it
+yourself double-encodes the value.
+
 ## Resolved Secrets and Provenance Boundaries
 
 - Leave ordinary external API inputs and third-party results unchanged. Add provenance handling only

.claude/commands/validate-integration.md

@@ -70,6 +70,15 @@ For **every** tool file, check:
 - [ ] Tool `description` is a concise one-liner describing what it does
 - [ ] Tool `version` is set (`'1.0.0'` or `'2.0.0'` for V2)
 
+### Request URL
+- [ ] A tool calling a third-party service returns an ABSOLUTE `https://...` URL
+- [ ] A tool calling Sim's own API declares it: a static `/api/...` string, or `internalRoute` from
+      `@/tools/internal-route` when the path is dynamic (query params via `.withQuery({...})`)
+- [ ] No builder returns a bare `` `/api/...` `` template string — that is treated as external and
+      will fail, because a `user-or-llm` param can produce the same string
+- [ ] No `encodeURIComponent` inside an `internalRoute` template (the tag already encodes, so this
+      double-encodes the value)
+
 ### Params
 - [ ] All required API params are marked `required: true`
 - [ ] All optional API params are marked `required: false`

.claude/rules/sim-integrations.md

@@ -14,6 +14,7 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc
 ## Hard rules (don't get these wrong)
 
 - Tool IDs are `snake_case` (`service_action`). Register tools in `tools/registry.ts`, blocks in `blocks/registry-maps.ts` (the `BLOCK_REGISTRY` config map + `BLOCK_META_REGISTRY` catalog-meta map, alphabetically — `blocks/registry.ts` holds only the accessor functions), triggers in `triggers/registry.ts`.
+- A tool that calls Sim's own API declares it: a static `request.url` string (`'/api/tools/{service}/{action}'`), or `` internalRoute`/api/table/${params.tableId}/rows` `` from `@/tools/internal-route` when the path is dynamic (query params via `.withQuery({...})`). The transport signs internal requests with the executing user's token, so that decision follows the tool's source, never the resolved string — a builder returning a bare `/api/...` string is treated as EXTERNAL, because a `user-or-llm` param can produce one. `internalRoute` encodes every `${...}`; never add `encodeURIComponent` inside the template.
 - Type coercions (`Number()`, etc.) belong in `tools.config.params` (runs at execution, after variable resolution) — never in `tools.config.tool` (runs at serialization; coercing there destroys dynamic `<Block.output>` references).
 - `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
 - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution.

.cursor/commands/add-integration.md

@@ -866,7 +866,12 @@ export const {service}UploadTool: ToolConfig<Params, Response> = {
     fileContent: { type: 'string', required: false, visibility: 'hidden' }, // Legacy
   },
   request: {
-    url: '/api/tools/{service}/upload',  // Internal route
+    // Internal route. A static string is a source literal, so the transport trusts it. When the
+    // path is dynamic, use `internalRoute` from '@/tools/internal-route' instead of a template
+    // string — a builder's plain `/api/...` string is treated as external, because a caller- or
+    // model-supplied param can produce one:
+    //   url: (params) => internalRoute`/api/tools/{service}/upload/${params.folderId}`
+    url: '/api/tools/{service}/upload',
     method: 'POST',
     body: (params) => ({
       accessToken: params.accessToken,

.cursor/commands/add-tools.md

@@ -139,6 +139,37 @@ export const {serviceName}{Action}Tool: ToolConfig<
 - Always explicitly set `required: true` or `required: false`
 - Optional params should have `required: false`
 
+## Internal Routes (calling Sim's own API)
+
+Most tools call a third-party service and `request.url` returns an absolute `https://...` URL. A
+tool that instead calls Sim's own API — a `/api/tools/{service}/{action}` proxy route, or a platform
+route like `/api/table/...` — must SAY SO, because the transport resolves those against the internal
+base URL and signs them with an internal token for the executing user.
+
+That declaration comes from the tool's source, never from the resolved string: a `user-or-llm` param
+can make any tool emit `/api/...` (the HTTP Request tool passes its `url` through verbatim, and a
+self-hosted integration with a blank host param collapses `${host}/api/v2/x` to `/api/v2/x`).
+
+```typescript
+import { internalRoute } from '@/tools/internal-route'
+
+// ✓ Static route — a source literal no param can influence
+url: '/api/tools/{service}/{action}',
+
+// ✓ Dynamic route — branded, and every interpolated id is percent-encoded for you
+url: (params) => internalRoute`/api/table/${params.tableId}/rows`,
+
+// ✓ Query params via withQuery (accepts an object or URLSearchParams; skips undefined/null)
+url: (params) => internalRoute`/api/logs`.withQuery({ workspaceId, limit: params.limit }),
+
+// ✗ Treated as EXTERNAL and will fail — a builder's plain string carries no provenance
+url: (params) => `/api/table/${params.tableId}/rows`,
+```
+
+`internalRoute` throws on a path outside `/api/` and on a query string inside the template. Never
+write `encodeURIComponent` inside the template — the tag already encodes each `${...}`, so doing it
+yourself double-encodes the value.
+
 ## Resolved Secrets and Provenance Boundaries
 
 - Leave ordinary external API inputs and third-party results unchanged. Add provenance handling only

.cursor/commands/validate-integration.md

@@ -65,6 +65,15 @@ For **every** tool file, check:
 - [ ] Tool `description` is a concise one-liner describing what it does
 - [ ] Tool `version` is set (`'1.0.0'` or `'2.0.0'` for V2)
 
+### Request URL
+- [ ] A tool calling a third-party service returns an ABSOLUTE `https://...` URL
+- [ ] A tool calling Sim's own API declares it: a static `/api/...` string, or `internalRoute` from
+      `@/tools/internal-route` when the path is dynamic (query params via `.withQuery({...})`)
+- [ ] No builder returns a bare `` `/api/...` `` template string — that is treated as external and
+      will fail, because a `user-or-llm` param can produce the same string
+- [ ] No `encodeURIComponent` inside an `internalRoute` template (the tag already encodes, so this
+      double-encodes the value)
+
 ### Params
 - [ ] All required API params are marked `required: true`
 - [ ] All optional API params are marked `required: false`