chore: import upstream snapshot with attribution

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

@@ -0,0 +1,466 @@
+---
+name: add-tools
+description: Create or update Sim tool configurations from service API docs, including typed params, request mapping, response transforms, outputs, and registry entries. Use when working in `apps/sim/tools/{service}/` or fixing tool definitions for an integration.
+---
+
+# Add Tools Skill
+
+You are an expert at creating tool configurations for Sim integrations. Your job is to read API documentation and create properly structured tool files.
+
+## Your Task
+
+When the user asks you to create tools for a service:
+1. Use Context7 or WebFetch to read the service's API documentation
+2. Create the tools directory structure
+3. Generate properly typed tool configurations
+
+## Hard Rule: No Guessed Response Schemas
+
+If the docs do not clearly show the response JSON for a tool, you MUST tell the user exactly which outputs are unknown and stop short of guessing.
+
+- Do NOT invent response field names
+- Do NOT infer nested paths from nearby endpoints
+- Do NOT guess array item shapes
+- Do NOT write `transformResponse` against unverified payloads
+
+If the response shape is unknown, do one of these instead:
+1. Ask the user for sample responses
+2. Ask the user for test credentials so you can verify live responses
+3. Implement only the endpoints whose outputs are documented
+4. Leave the tool unimplemented and explicitly say why
+
+## Directory Structure
+
+Create files in `apps/sim/tools/{service}/`:
+```
+tools/{service}/
+├── index.ts      # Barrel export
+├── types.ts      # Parameter & response types
+└── {action}.ts   # Individual tool files (one per operation)
+```
+
+## Tool Configuration Structure
+
+Every tool MUST follow this exact structure:
+
+```typescript
+import type { {ServiceName}{Action}Params } from '@/tools/{service}/types'
+import type { ToolConfig } from '@/tools/types'
+
+interface {ServiceName}{Action}Response {
+  success: boolean
+  output: {
+    // Define output structure here
+  }
+}
+
+export const {serviceName}{Action}Tool: ToolConfig<
+  {ServiceName}{Action}Params,
+  {ServiceName}{Action}Response
+> = {
+  id: '{service}_{action}',           // snake_case, matches tool name
+  name: '{Service} {Action}',         // Human readable
+  description: 'Brief description',   // One sentence
+  version: '1.0.0',
+
+  // OAuth config (if service uses OAuth)
+  oauth: {
+    required: true,
+    provider: '{service}',            // Must match OAuth provider ID
+  },
+
+  params: {
+    // Hidden params (system-injected, only use hidden for oauth accessToken)
+    accessToken: {
+      type: 'string',
+      required: true,
+      visibility: 'hidden',
+      description: 'OAuth access token',
+    },
+    // User-only params (credentials, api key, IDs user must provide)
+    someId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'The ID of the resource',
+    },
+    // User-or-LLM params (everything else, can be provided by user OR computed by LLM)
+    query: {
+      type: 'string',
+      required: false,                // Use false for optional
+      visibility: 'user-or-llm',
+      description: 'Search query',
+    },
+  },
+
+  request: {
+    url: (params) => `https://api.service.com/v1/resource/${params.id}`,
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.accessToken}`,
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => ({
+      // Request body - only for POST/PUT/PATCH
+      // Trim ID fields to prevent copy-paste whitespace errors:
+      // userId: params.userId?.trim(),
+    }),
+  },
+
+  transformResponse: async (response: Response) => {
+    const data = await response.json()
+    return {
+      success: true,
+      output: {
+        // Map API response to output
+        // Use ?? null for nullable fields
+        // Use ?? [] for optional arrays
+      },
+    }
+  },
+
+  outputs: {
+    // Define each output field
+  },
+}
+```
+
+## Critical Rules for Parameters
+
+### Visibility Options
+- `'hidden'` - System-injected (OAuth tokens, internal params). User never sees.
+- `'user-only'` - User must provide (credentials, api keys, account-specific IDs)
+- `'user-or-llm'` - User provides OR LLM can compute (search queries, content, filters, most fall into this category)
+
+### Parameter Types
+- `'string'` - Text values
+- `'number'` - Numeric values
+- `'boolean'` - True/false
+- `'json'` - Complex objects (NOT 'object', use 'json')
+- `'file'` - Single file
+- `'file[]'` - Multiple files
+
+### Required vs Optional
+- Always explicitly set `required: true` or `required: false`
+- Optional params should have `required: false`
+
+## Critical Rules for Outputs
+
+### Output Types
+- `'string'`, `'number'`, `'boolean'` - Primitives
+- `'json'` - Complex objects (use this, NOT 'object')
+- `'array'` - Arrays with `items` property
+- `'object'` - Objects with `properties` property
+
+### Optional Outputs
+Add `optional: true` for fields that may not exist in the response:
+```typescript
+closedAt: {
+  type: 'string',
+  description: 'When the issue was closed',
+  optional: true,
+},
+```
+
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **always define the inner structure** using `properties` so downstream consumers know what fields are available:
+
+```typescript
+// BAD: Opaque json with no info about what's inside
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+},
+
+// GOOD: Define the known properties
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+  properties: {
+    id: { type: 'string', description: 'Unique ID' },
+    status: { type: 'string', description: 'Current status' },
+    count: { type: 'number', description: 'Total count' },
+  },
+},
+```
+
+For arrays of objects, define the item structure:
+```typescript
+items: {
+  type: 'array',
+  description: 'List of items',
+  items: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Item ID' },
+      name: { type: 'string', description: 'Item name' },
+    },
+  },
+},
+```
+
+Only use bare `type: 'json'` without `properties` when the shape is truly dynamic or unknown.
+
+If the response shape is unknown because the docs do not provide it, you MUST tell the user and stop. Unknown is not the same as dynamic. Never guess outputs.
+
+## Critical Rules for transformResponse
+
+### Handle Nullable Fields
+ALWAYS use `?? null` for fields that may be undefined:
+```typescript
+transformResponse: async (response: Response) => {
+  const data = await response.json()
+  return {
+    success: true,
+    output: {
+      id: data.id,
+      title: data.title,
+      body: data.body ?? null,           // May be undefined
+      assignee: data.assignee ?? null,   // May be undefined
+      labels: data.labels ?? [],         // Default to empty array
+      closedAt: data.closed_at ?? null,  // May be undefined
+    },
+  }
+}
+```
+
+### Never Output Raw JSON Dumps
+DON'T do this:
+```typescript
+output: {
+  data: data,  // BAD - raw JSON dump
+}
+```
+
+DO this instead - extract meaningful fields:
+```typescript
+output: {
+  id: data.id,
+  name: data.name,
+  status: data.status,
+  metadata: {
+    createdAt: data.created_at,
+    updatedAt: data.updated_at,
+  },
+}
+```
+
+## Types File Pattern
+
+Create `types.ts` with interfaces for all params and responses:
+
+```typescript
+import type { ToolResponse } from '@/tools/types'
+
+// Parameter interfaces
+export interface {Service}{Action}Params {
+  accessToken: string
+  requiredField: string
+  optionalField?: string
+}
+
+// Response interfaces (extend ToolResponse)
+export interface {Service}{Action}Response extends ToolResponse {
+  output: {
+    field1: string
+    field2: number
+    optionalField?: string | null
+  }
+}
+```
+
+## Index.ts Barrel Export Pattern
+
+```typescript
+// Export all tools
+export { serviceTool1 } from './{action1}'
+export { serviceTool2 } from './{action2}'
+
+// Export types
+export * from './types'
+```
+
+## Registering Tools
+
+After creating tools:
+1. Import tools in `apps/sim/tools/registry.ts`
+2. Add to the `tools` object with snake_case keys (alphabetically):
+```typescript
+import { serviceActionTool } from '@/tools/{service}'
+
+export const tools = {
+  // ... existing tools ...
+  {service}_{action}: serviceActionTool,
+}
+```
+
+## Wiring Tools into the Block (Required)
+
+After registering in `tools/registry.ts`, you MUST also update the block definition at `apps/sim/blocks/blocks/{service}.ts`. This is not optional — tools are only usable from the UI if they are wired into the block.
+
+### 1. Add to `tools.access`
+
+```typescript
+tools: {
+  access: [
+    // existing tools...
+    'service_new_action',   // Add every new tool ID here
+  ],
+  config: { ... }
+}
+```
+
+### 2. Add operation dropdown options
+
+If the block uses an operation dropdown, add an option for each new tool:
+
+```typescript
+{
+  id: 'operation',
+  type: 'dropdown',
+  options: [
+    // existing options...
+    { label: 'New Action', id: 'new_action' },   // id maps to what tools.config.tool returns
+  ],
+}
+```
+
+### 3. Add subBlocks for new tool params
+
+For each new tool, add subBlocks covering all its required params (and optional ones where useful). Apply `condition` to show them only for the right operation, and mark required params with `required`:
+
+```typescript
+// Required param for new_action
+{
+  id: 'someParam',
+  title: 'Some Param',
+  type: 'short-input',
+  placeholder: 'e.g., value',
+  condition: { field: 'operation', value: 'new_action' },
+  required: { field: 'operation', value: 'new_action' },
+},
+// Optional param — put in advanced mode
+{
+  id: 'optionalParam',
+  title: 'Optional Param',
+  type: 'short-input',
+  condition: { field: 'operation', value: 'new_action' },
+  mode: 'advanced',
+},
+```
+
+### 4. Update `tools.config.tool`
+
+Ensure the tool selector returns the correct tool ID for every new operation. The simplest pattern:
+
+```typescript
+tool: (params) => `service_${params.operation}`,
+// If operation dropdown IDs already match tool IDs, this requires no change.
+```
+
+If the dropdown IDs differ from tool IDs, add explicit mappings:
+
+```typescript
+tool: (params) => {
+  const map: Record<string, string> = {
+    new_action: 'service_new_action',
+    // ...
+  }
+  return map[params.operation] ?? `service_${params.operation}`
+},
+```
+
+### 5. Update `tools.config.params`
+
+Add any type coercions needed for new params (runs at execution time, after variable resolution):
+
+```typescript
+params: (params) => {
+  const result: Record<string, unknown> = {}
+  if (params.limit != null && params.limit !== '') result.limit = Number(params.limit)
+  if (params.newParamName) result.toolParamName = params.newParamName  // rename if IDs differ
+  return result
+},
+```
+
+### 6. Add new outputs
+
+Add any new fields returned by the new tools to the block `outputs`:
+
+```typescript
+outputs: {
+  // existing outputs...
+  newField: { type: 'string', description: 'Description of new field' },
+}
+```
+
+### 7. Add new inputs
+
+Add new subBlock param IDs to the block `inputs` section:
+
+```typescript
+inputs: {
+  // existing inputs...
+  someParam: { type: 'string', description: 'Param description' },
+  optionalParam: { type: 'string', description: 'Optional param description' },
+}
+```
+
+### Block wiring checklist
+
+- [ ] New tool IDs added to `tools.access`
+- [ ] Operation dropdown has an option for each new tool
+- [ ] SubBlocks cover all required params for each new tool
+- [ ] SubBlocks have correct `condition` (only show for the right operation)
+- [ ] Optional/rarely-used params set to `mode: 'advanced'`
+- [ ] `tools.config.tool` returns correct ID for every new operation
+- [ ] `tools.config.params` handles any ID remapping or type coercions
+- [ ] New outputs added to block `outputs`
+- [ ] New params added to block `inputs`
+
+## V2 Tool Pattern
+
+If creating V2 tools (API-aligned outputs), use `_v2` suffix:
+- Tool ID: `{service}_{action}_v2`
+- Variable name: `{action}V2Tool`
+- Version: `'2.0.0'`
+- Outputs: Flat, API-aligned (no content/metadata wrapper)
+
+## Naming Convention
+
+All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase for tool IDs.
+
+## Checklist Before Finishing
+
+- [ ] All tool IDs use snake_case
+- [ ] All params have explicit `required: true` or `required: false`
+- [ ] All params have appropriate `visibility`
+- [ ] All nullable response fields use `?? null`
+- [ ] All optional outputs have `optional: true`
+- [ ] No raw JSON dumps in outputs
+- [ ] Types file has all interfaces
+- [ ] Index.ts exports all tools and re-exports types (`export * from './types'`)
+- [ ] Tools registered in `tools/registry.ts`
+- [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs
+
+## Final Validation (Required)
+
+After creating all tools, you MUST validate every tool before finishing:
+
+1. **Read every tool file** you created — do not skip any
+2. **Cross-reference with the API docs** to verify:
+   - All required params are marked `required: true`
+   - All optional params are marked `required: false`
+   - Param types match the API (string, number, boolean, json)
+   - Request URL, method, headers, and body match the API spec
+   - `transformResponse` extracts the correct fields from the API response
+   - All output fields match what the API actually returns
+   - No fields are missing from outputs that the API provides
+   - No extra fields are defined in outputs that the API doesn't return
+   - Every output field and JSON path is backed by docs or live-verified sample responses
+3. **Verify consistency** across tools:
+   - Shared types in `types.ts` match all tools that use them
+   - Tool IDs in the barrel export match the tool file definitions
+   - Error handling is consistent (error checks, meaningful messages)
+4. **If any response schema is still unknown**, explicitly tell the user instead of guessing

.agents/skills/add-tools/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Add Tools"
+  short_description: "Build Sim tools from API docs"
+  brand_color: "#EA580C"
+  default_prompt: "Use $add-tools to create or update Sim tool definitions from service API docs."