@synap-core/workspace-templates 0.12.0 → 0.24.0

package/capabilities/dropbox.capability.json

@@ -0,0 +1,281 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "dropbox",
+    "name": "Dropbox — Files & Storage",
+    "description": "Dropbox file operations through one Nango OAuth connection (API v2, RPC style): list a folder, search, get metadata, mint a temporary download link, create a folder, and delete. Read verbs auto-run; writes route through the capability-execution gate. Connect your Dropbox account to use it.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "dropbox",
+    "name": "Dropbox — Files & Storage",
+    "description": "Dropbox file operations through ONE Nango OAuth connection (Dropbox API v2 — RPC style: every verb POSTs a JSON body to api.dropboxapi.com/2). READ your files — list a folder's entries, search names and content, inspect one item's metadata, and mint a temporary (4-hour) download link. WRITE — create a folder, delete a file or folder. PRECONDITION: the 'dropbox' integration must be declared + configured on the pod's Nango (scopes: files.metadata.read, files.content.read, and files.content.write for create_folder/delete) and the acting user must connect their Dropbox account via Connectors; the dispatcher resolves the most-recent dropbox connection automatically. Paths are RELATIVE to the Nango dropbox integration's base URL (api.dropboxapi.com/2) — no baseUrlOverride, so no provider-proxy-host allowlist entry is needed. Reads (list/search/get/get_temporary_link) auto-run; writes (create_folder, delete) are side-effecting and route through the capability-execution gate. BODY TYPING — IMPORTANT: the declarative engine interpolates `{{param}}` into a JSON body as STRINGS ONLY, and Dropbox type-checks its RPC bodies (a string where a uint32/boolean is expected returns 400 'expected uint64, got string'). So NO numeric/boolean body params are declared here: `limit` and `recursive` are omitted from list_folder and `max_results` from search_v2, letting Dropbox apply its own defaults; declaring them would ship a verb that always errors. A typed numeric body param needs substrate support before it can be added. NOT INCLUDED: raw binary download/upload — `files/download` and `files/upload` carry their argument in the `Dropbox-API-Arg` HEADER (which the engine cannot interpolate), live on the separate content.dropboxapi.com host, and return raw bytes with the metadata in a response header (which responseShape cannot read). Use `dropbox_get_temporary_link` to obtain a download URL instead. Two shaping limits worth knowing: Dropbox's `.tag` union discriminator (a key that literally begins with a dot) is not addressable through the engine's dot-path getter — a segment named `.tag` splits to an empty key — so list/search entries carry no explicit file-vs-folder mark (a folder is an entry whose `size` is null); and an unscoped search sends `options.path` as an empty string rather than omitting the key, because only QUERY keys are dropped when empty, never BODY keys. Response-field shaping is best-effort and confirmed against the live API at first run.",
+    "params": [],
+    "vault": [],
+    "tools": [
+      {
+        "name": "dropbox",
+        "kind": "provider",
+        "description": "Dropbox API v2 access through Nango. credentialRef nango://dropbox resolves the user's Dropbox connection (Connection-Id + Provider-Config-Key) and proxies to the integration's base URL (api.dropboxapi.com/2).",
+        "credentialRef": "nango://dropbox",
+        "executor": "is-agent",
+        "config": {
+          "providerConfigKey": "dropbox"
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "dropbox_list_folder",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the entries (files and folders) in a Dropbox folder. Args: { path?: string (Dropbox path, e.g. \"/Projects\"; omit or pass \"\" for the root) }.",
+        "requires": [
+          "dropbox"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "path": "string?"
+        },
+        "providerSpec": {
+          "tool": "dropbox",
+          "method": "POST",
+          "pathTemplate": "/files/list_folder",
+          "body": {
+            "path": "{{path}}"
+          },
+          "paramMapping": {
+            "path": {
+              "default": ""
+            }
+          },
+          "responseShape": {
+            "collectionPath": "entries",
+            "collectionAs": "entries",
+            "item": {
+              "name": "name",
+              "path": "path_display",
+              "id": "id",
+              "size": "size",
+              "clientModified": "client_modified",
+              "serverModified": "server_modified"
+            },
+            "scalar": {
+              "hasMore": "has_more",
+              "cursor": "cursor"
+            }
+          }
+        }
+      },
+      {
+        "name": "dropbox_search",
+        "intent": "search_external",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Searches the user's Dropbox by file name and content. Args: { query: string (max 1000 chars), path?: string (folder to scope the search to; omit or pass \"\" to search everywhere) }.",
+        "requires": [
+          "dropbox"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "query": "string",
+          "path": "string?"
+        },
+        "providerSpec": {
+          "tool": "dropbox",
+          "method": "POST",
+          "pathTemplate": "/files/search_v2",
+          "body": {
+            "query": "{{query}}",
+            "options": {
+              "path": "{{path}}"
+            }
+          },
+          "paramMapping": {
+            "query": {
+              "required": true
+            },
+            "path": {
+              "default": ""
+            }
+          },
+          "responseShape": {
+            "collectionPath": "matches",
+            "collectionAs": "matches",
+            "item": {
+              "name": "metadata.metadata.name",
+              "path": "metadata.metadata.path_display",
+              "id": "metadata.metadata.id",
+              "size": "metadata.metadata.size",
+              "serverModified": "metadata.metadata.server_modified"
+            },
+            "scalar": {
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "dropbox_get_metadata",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Gets metadata (name, path, id, size, timestamps, rev) for one file or folder. Args: { path: string (e.g. \"/Docs/report.pdf\"; id:… / rev:… refs are also accepted) }.",
+        "requires": [
+          "dropbox"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "path": "string"
+        },
+        "providerSpec": {
+          "tool": "dropbox",
+          "method": "POST",
+          "pathTemplate": "/files/get_metadata",
+          "body": {
+            "path": "{{path}}"
+          },
+          "paramMapping": {
+            "path": {
+              "required": true
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "name": "name",
+              "path": "path_display",
+              "id": "id",
+              "size": "size",
+              "rev": "rev",
+              "clientModified": "client_modified",
+              "serverModified": "server_modified"
+            }
+          }
+        }
+      },
+      {
+        "name": "dropbox_get_temporary_link",
+        "intent": "manage_file",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Returns a temporary download URL for a file — the way to get at a Dropbox file's bytes without streaming them. The link expires after 4 hours. Args: { path: string }.",
+        "requires": [
+          "dropbox"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "path": "string"
+        },
+        "providerSpec": {
+          "tool": "dropbox",
+          "method": "POST",
+          "pathTemplate": "/files/get_temporary_link",
+          "body": {
+            "path": "{{path}}"
+          },
+          "paramMapping": {
+            "path": {
+              "required": true
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "link": "link",
+              "name": "metadata.name",
+              "path": "metadata.path_display",
+              "size": "metadata.size"
+            }
+          }
+        }
+      },
+      {
+        "name": "dropbox_create_folder",
+        "intent": "manage_file",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Creates a folder at the given Dropbox path. Side-effecting write — routes through the capability-execution gate. Args: { path: string (e.g. \"/Projects/2026\") }.",
+        "requires": [
+          "dropbox"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "path": "string"
+        },
+        "providerSpec": {
+          "tool": "dropbox",
+          "method": "POST",
+          "pathTemplate": "/files/create_folder_v2",
+          "body": {
+            "path": "{{path}}",
+            "autorename": false
+          },
+          "paramMapping": {
+            "path": {
+              "required": true
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "name": "metadata.name",
+              "path": "metadata.path_display",
+              "id": "metadata.id"
+            }
+          }
+        }
+      },
+      {
+        "name": "dropbox_delete",
+        "intent": "manage_file",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Deletes a file or folder at the given Dropbox path (a folder deletes its contents too). Side-effecting write — routes through the capability-execution gate. Args: { path: string }.",
+        "requires": [
+          "dropbox"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "path": "string"
+        },
+        "providerSpec": {
+          "tool": "dropbox",
+          "method": "POST",
+          "pathTemplate": "/files/delete_v2",
+          "body": {
+            "path": "{{path}}"
+          },
+          "paramMapping": {
+            "path": {
+              "required": true
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "name": "metadata.name",
+              "path": "metadata.path_display",
+              "id": "metadata.id"
+            }
+          }
+        }
+      }
+    ],
+    "provides": [
+      "fetch_record",
+      "list_records",
+      "manage_file",
+      "search_external"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/exa.capability.json

@@ -0,0 +1,109 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "exa",
+    "name": "Exa — Web Search",
+    "description": "Search the web with Exa to discover companies, people, news and articles you don't know about yet, or find pages similar to one you have. Search only; results are saved only if you choose to. Needs an Exa API key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "exa",
+    "name": "Exa — Neural Web Search",
+    "description": "AI-native web search and discovery — the DISCOVERY pillar the scrape/act connectors can't provide. Apify scrapes sources you already name, Unipile acts in accounts you own, Nango calls APIs you're authed to; Exa answers the question none of them can: 'find things across the web I don't know about yet' (new competitors, people voicing a problem, fresh content on a topic). This is what makes a kind-bound radar SELF-GENERATING — it discovers new entities rather than only re-scanning known ones. Verified against Exa's live API docs (POST https://api.exa.ai/search, x-api-key header, category filter incl. company/people/news, /findSimilar), not guessed. Skills are READ-ONLY search primitives with no side effects: a radar playbook composes them (fan-out, then resolve-or-create deduplicated entities via the pod's identity-resolution door) — the search skills themselves never create entities, keeping WHAT-to-search separate from WHAT-to-do-with-results. PRECONDITION: an Exa account API key (dashboard.exa.ai -> API Keys).",
+    "params": [
+      {
+        "name": "exaApiKey",
+        "label": "Exa API key",
+        "type": "text",
+        "required": true,
+        "description": "The Exa API key (dashboard.exa.ai -> API Keys). Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "exaApiKeySecret",
+        "name": "{{name}} Exa API key",
+        "value": "{{exaApiKey}}",
+        "type": "api_key",
+        "description": "Exa API key for the exa_api connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "exa_api",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the Exa REST API (https://api.exa.ai). The applier injects the vaulted API key into the `x-api-key` header (raw key, no prefix — Exa's auth scheme); its credentialRef is remapped to the runtime vault://<id> at apply time.",
+        "credentialRef": "exaApiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.exa.ai",
+          "auth": {
+            "in": "header",
+            "name": "x-api-key",
+            "prefix": ""
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "exa_search",
+        "intent": "search_web",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Neural web search — finds pages semantically matching a query (not just keyword-matching), the discovery engine for radars. Read-only, no side effects. Use `category` to narrow to a kind of result: 'company' (find competitors/vendors), 'people' (find leads/prospects voicing a need), 'news', 'research paper', 'financial report'. Returns normalized results { title, url, publishedDate, author, text, summary, entities }. Args: { query: string, numResults?: number (default 10, max 100), category?: string, type?: string ('auto'|'fast'|'deep'), includeDomains?: string[], excludeDomains?: string[], startPublishedDate?: ISO8601, endPublishedDate?: ISO8601, summary?: boolean }.",
+        "requires": [
+          "exa_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 45,
+        "parameters": {
+          "query": "string",
+          "numResults": "number?",
+          "category": "string?",
+          "type": "string?",
+          "includeDomains": "array?",
+          "excludeDomains": "array?",
+          "startPublishedDate": "string?",
+          "endPublishedDate": "string?",
+          "summary": "boolean?"
+        },
+        "code": "// Neural web search via Exa. Executor wraps this body as (async (args, context) => { <code> });\n// use args directly and `return`. callProvider('exa_api','POST','/search',body) resolves the\n// exa_api tool by NAME and injects the vaulted key as `x-api-key: <key>` (config.auth).\n// Build the body omitting undefined optional fields — Exa rejects empty enum values.\nconst query = String(args?.query ?? '').trim();\nif (!query) throw new Error('exa_search: query is required');\n\nconst n = Number(args?.numResults);\nconst numResults = Number.isFinite(n) ? Math.max(1, Math.min(100, Math.trunc(n))) : 10;\n\nconst contents = { text: { maxCharacters: 1500 } };\nif (args?.summary === true) contents.summary = true;\n\nconst body = { query, numResults, contents };\nif (typeof args?.category === 'string' && args.category.trim()) body.category = args.category.trim();\nif (typeof args?.type === 'string' && args.type.trim()) body.type = args.type.trim();\nif (Array.isArray(args?.includeDomains) && args.includeDomains.length) body.includeDomains = args.includeDomains;\nif (Array.isArray(args?.excludeDomains) && args.excludeDomains.length) body.excludeDomains = args.excludeDomains;\nif (typeof args?.startPublishedDate === 'string' && args.startPublishedDate.trim()) body.startPublishedDate = args.startPublishedDate.trim();\nif (typeof args?.endPublishedDate === 'string' && args.endPublishedDate.trim()) body.endPublishedDate = args.endPublishedDate.trim();\n\nconst res = await callProvider('exa_api', 'POST', '/search', body);\nconst payload = res?.body ?? res;\nconst rows = Array.isArray(payload?.results) ? payload.results : [];\nconst results = rows.map((r) => ({\n  title: r?.title ?? null,\n  url: r?.url ?? null,\n  publishedDate: r?.publishedDate ?? null,\n  author: r?.author ?? null,\n  text: r?.text ?? null,\n  summary: r?.summary ?? null,\n  entities: r?.entities ?? null,\n}));\nreturn { query, count: results.length, results, costDollars: payload?.costDollars ?? null };",
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "exa_find_similar",
+        "intent": "search_external",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Finds web pages semantically SIMILAR to a given URL — 'more sites like this competitor / this article'. Read-only, no side effects. Great for expanding a radar from one known entity to its neighbours (e.g. from one competitor's site to other companies in the same space). Returns normalized results { title, url, publishedDate, author, text }. Args: { url: string, numResults?: number (default 10, max 100), excludeSourceDomain?: boolean (default true — don't return the input site itself) }.",
+        "requires": [
+          "exa_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 45,
+        "parameters": {
+          "url": "string",
+          "numResults": "number?",
+          "excludeSourceDomain": "boolean?"
+        },
+        "code": "// Find pages similar to a URL via Exa's /findSimilar. Executor wraps this body as\n// (async (args, context) => { <code> }); use args directly and `return`.\n// callProvider('exa_api','POST','/findSimilar',body) injects `x-api-key` via config.auth.\nconst url = String(args?.url ?? '').trim();\nif (!url) throw new Error('exa_find_similar: url is required');\n\nconst n = Number(args?.numResults);\nconst numResults = Number.isFinite(n) ? Math.max(1, Math.min(100, Math.trunc(n))) : 10;\n\nconst body = {\n  url,\n  numResults,\n  excludeSourceDomain: args?.excludeSourceDomain !== false,\n  contents: { text: { maxCharacters: 1500 } },\n};\n\nconst res = await callProvider('exa_api', 'POST', '/findSimilar', body);\nconst payload = res?.body ?? res;\nconst rows = Array.isArray(payload?.results) ? payload.results : [];\nconst results = rows.map((r) => ({\n  title: r?.title ?? null,\n  url: r?.url ?? null,\n  publishedDate: r?.publishedDate ?? null,\n  author: r?.author ?? null,\n  text: r?.text ?? null,\n}));\nreturn { url, count: results.length, results, costDollars: payload?.costDollars ?? null };",
+        "metadata": {
+          "readOnly": true
+        }
+      }
+    ],
+    "provides": [
+      "search_web",
+      "search_external"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/fal-ai.capability.json

@@ -0,0 +1,83 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "fal-ai",
+    "name": "fal.ai — Image Generation",
+    "description": "Generate images from a text prompt with fal.ai models such as FLUX, and save each result as a bookmark once you approve it. Needs a fal.ai API key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "fal-ai",
+    "name": "fal.ai Image Generation",
+    "description": "AI image generation via the fal.ai synchronous REST API (base https://fal.run/<model-id>) using API-key auth. Stores the fal.ai key in the vault, registers one HTTP API tool that authenticates with `Authorization: Key <fal_key>`, and seeds one write skill (fal_generate_image) that calls the model, then proposes the result as a bookmark entity carrying the image URL (proposal-gated). GOTCHA: fal.run blocks the request until generation finishes (fast models like flux/schnell: ~2-6s; heavier models can take much longer) — this is the SYNCHRONOUS endpoint, not the async queue.fal.run submit/poll flow (which this template does NOT implement; a queue+poll variant would need a code skill polling `status_url`, since ProviderVerbSpec has no poll primitive). The `model` arg is the fal model id path (e.g. 'fal-ai/flux/schnell', 'fal-ai/flux/dev', 'fal-ai/recraft-v3') appended directly to the base URL — different fal models can take different request/response shapes; this skill sends the common contract ({ prompt, num_images, image_size } plus, when given, image_urls / aspect_ratio / seed in; { images: [{ url, width, height }] } out), which covers the flux family, most fal text-to-image models and the image_urls edit/reference models (e.g. fal-ai/nano-banana/edit), but is not universal. Only those declared inputs are forwarded, each validated and capped. GOTCHA: there is no first-class 'generated image / document' entity in Synap reachable from a capability skill (propose.entity has no document-creation counterpart, and the 'file'/'capture' profiles are hideFromCreate — reserved for system-driven creation via the document-upload pipeline) — this template proposes a 'bookmark' entity (Saved URL) holding the image URL as the closest legitimate fit. PRECONDITION: a fal.ai account with an API key (https://fal.ai/dashboard/keys). Pass it as `falApiKey`.",
+    "params": [
+      {
+        "name": "falApiKey",
+        "label": "fal.ai API key",
+        "type": "text",
+        "required": true,
+        "description": "The fal.ai API key (https://fal.ai/dashboard/keys). Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "falApiKeySecret",
+        "name": "{{name}} fal.ai API key",
+        "value": "{{falApiKey}}",
+        "type": "api_key",
+        "description": "fal.ai API key for the fal_api connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "fal_api",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the fal.ai synchronous run API (https://fal.run/<model-id>). The applier injects the vaulted API key into the Authorization header as `Key <key>`; its credentialRef is remapped to the runtime vault://<id> at apply time.",
+        "credentialRef": "falApiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://fal.run",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Key "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "fal_generate_image",
+        "intent": "generate_media",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Generates images from a text prompt via fal.ai (proposal-gated) and proposes each result as a bookmark entity holding its image URL. Args: { prompt: string, model?: string (fal model id, default 'fal-ai/flux/schnell'; edit/reference models such as 'fal-ai/nano-banana/edit' need imageUrls), imageSize?: string (default 'square_hd' when no aspectRatio, e.g. 'square'|'portrait_4_3'|'landscape_16_9'), numImages?: string (default '1', max 4), imageUrls?: string[] (1-8 public http(s) reference or source image URLs, sent as image_urls), images?: pod file entity ids (reference images from the pod; the pod signs them at run time and they join imageUrls in image_urls, 8 at most in all), aspectRatio?: string (e.g. '16:9', '1:1', 'auto'; sent as aspect_ratio, used by nano-banana), seed?: string (whole number, for reproducible results) }. Only these args reach fal. Returns { imageUrl (first), imageUrls (all), imageCount, seed, bookmarks: [{ url, status, proposalId?, error? }], bookmarkFailures }; a failed bookmark write is reported there and never fails the run.",
+        "requires": [
+          "fal_api"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 120,
+        "parameters": {
+          "prompt": "string",
+          "model": "string?",
+          "imageSize": "string?",
+          "numImages": "string?",
+          "imageUrls": "array?",
+          "images": "file[]:url?",
+          "aspectRatio": "string?",
+          "seed": "string?"
+        },
+        "code": "// Generate an image via fal.ai's synchronous run endpoint (side-effecting write:\n// calls a billed external API). Executor wraps this body as\n// (async (args, context) => { <code> }); use args directly and `return`.\n// callProvider(tool, method, path, body?, opts?) resolves the fal_api tool by\n// NAME, injects the vaulted key as Authorization: Key <key>, and uses the\n// tool's config.baseUrl = https://fal.run. The model id becomes the path.\n//\n// MODEL INPUTS: only the DECLARED args reach fal, each validated and capped:\n// imageUrls -> image_urls (edit / reference models such as\n// fal-ai/nano-banana/edit), aspectRatio -> aspect_ratio, seed -> seed. Nothing\n// else is forwarded, so a caller cannot smuggle a key or an arbitrary field\n// into the billed request. A fal-style snake_case spelling of a declared arg\n// is REFUSED with the name to use, never silently dropped (a dropped\n// image_urls is what turned an edit call into a fal 422).\nconst prompt = String(args?.prompt ?? '').trim();\nif (!prompt) throw new Error('fal_generate_image: prompt is required');\nconst SNAKE = { image_urls: 'imageUrls', aspect_ratio: 'aspectRatio', image_size: 'imageSize', num_images: 'numImages' };\nfor (const k of Object.keys(SNAKE)) {\n  if (args && args[k] !== undefined) throw new Error('fal_generate_image: pass ' + SNAKE[k] + ', not ' + k);\n}\nconst model = String(args?.model ?? 'fal-ai/flux/schnell').trim() || 'fal-ai/flux/schnell';\nif (!/^[a-z0-9][a-z0-9._-]*(\\/[a-z0-9][a-z0-9._-]*){1,4}$/i.test(model)) {\n  throw new Error('fal_generate_image: model must be a fal model id such as fal-ai/flux/schnell');\n}\nconst numImagesRaw = Number(args?.numImages ?? 1);\nconst numImages = Number.isFinite(numImagesRaw) && numImagesRaw > 0 ? Math.min(Math.floor(numImagesRaw), 4) : 1;\n\nconst payload = { prompt, num_images: numImages };\nlet imageUrls = [];\nif (args?.imageUrls !== undefined) {\n  if (!Array.isArray(args.imageUrls)) throw new Error('fal_generate_image: imageUrls must be an array of URLs');\n  imageUrls = args.imageUrls.map((u) => String(u ?? '').trim()).filter((u) => u.length > 0);\n  if (imageUrls.length === 0) throw new Error('fal_generate_image: imageUrls is empty');\n  if (imageUrls.length > 8) throw new Error('fal_generate_image: imageUrls takes at most 8 URLs');\n  for (const u of imageUrls) {\n    // Public http(s) only, no userinfo (user:pass@) and no data:/file:/vault: refs.\n    if (u.length > 2048 || !/^https?:\\/\\/[^\\s\\/?#@]+([\\/?#][^\\s]*)?$/i.test(u)) {\n      throw new Error('fal_generate_image: imageUrls must be public http(s) URLs without credentials (got ' + u.slice(0, 80) + ')');\n    }\n  }\n}\n// `images` are POD FILES (declared \"file[]:url?\", backend #469): the caller passes\n// file entity ids and the pod swaps each for a fresh signed URL at run time (6 h\n// for this async verb). Those URLs are sent to fal and never stored or echoed.\nlet podImages = [];\nif (args?.images !== undefined && args?.images !== null) {\n  if (!Array.isArray(args.images)) throw new Error('fal_generate_image: images must be a list of pod file ids');\n  podImages = args.images.map((u) => String(u ?? '').trim()).filter((u) => u.length > 0);\n  for (const u of podImages) {\n    if (u.length > 4096 || !/^https:\\/\\/[^\\s\\/?#@]+([\\/?#][^\\s]*)?$/i.test(u)) {\n      throw new Error('fal_generate_image: images did not arrive as signed pod file URLs; pass pod file entity ids');\n    }\n  }\n}\nconst references = imageUrls.concat(podImages);\nif (references.length > 8) throw new Error('fal_generate_image: imageUrls and images take at most 8 images together');\nif (references.length > 0) payload.image_urls = references;\nconst aspectRatio = args?.aspectRatio === undefined ? '' : String(args.aspectRatio).trim();\nif (aspectRatio) {\n  if (!/^(auto|\\d{1,2}:\\d{1,2})$/.test(aspectRatio)) throw new Error('fal_generate_image: aspectRatio must be like 16:9, 1:1 or auto');\n  payload.aspect_ratio = aspectRatio;\n}\n// image_size: sent when asked for, or as the default when no aspectRatio\n// is given (flux-family models size by image_size; nano-banana ignores it\n// and sizes by aspect_ratio).\nconst imageSize = args?.imageSize === undefined ? '' : String(args.imageSize).trim();\nif (imageSize || !aspectRatio) payload.image_size = imageSize || 'square_hd';\nif (args?.seed !== undefined && String(args.seed).trim() !== '') {\n  const seed = Number(args.seed);\n  if (!Number.isSafeInteger(seed) || seed < 0 || seed > 4294967295) throw new Error('fal_generate_image: seed must be a whole number from 0 to 4294967295');\n  payload.seed = seed;\n}\n\nconst res = await callProvider('fal_api', 'POST', '/' + model, payload);\n// The capability-execution gate may return a PROPOSAL envelope ({ proposed,\n// proposalId }) instead of executing — that proposal IS the record; return early\n// WITHOUT also filing a bookmark (no double-proposal).\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, prompt, model };\n}\nconst ok = typeof res?.status === 'number' && res.status >= 200 && res.status < 300;\nconst body = res?.body ?? res;\nconst images = (Array.isArray(body?.images) ? body.images : []).filter((im) => typeof im?.url === 'string' && im.url);\nif (!ok || images.length === 0) {\n  throw new Error('fal_generate_image: generation failed or returned no image (status ' + (res?.status ?? 'unknown') + ')');\n}\nconst urls = images.map((im) => im.url);\nconst outSeed = typeof body?.seed === 'number' ? body.seed : (payload.seed ?? null);\n\n// One bookmark per image: each variant is kept or rejected on its own.\n// TITLE = prompt + the image's own fal file id. A bookmark's identity is its\n// url, but the duplicate door's name leg compares titles: a title made of the\n// truncated prompt alone was the SAME for every variant and every re-run, so\n// each image after the first was filed as POSSIBLE_DUPLICATE, sat pending,\n// and ate the agent's pending-proposal budget until generation itself failed.\n// A failed bookmark write never fails the run: the images are generated and\n// billed, so their URLs are returned and the failure is reported beside them.\nconst shortPrompt = prompt.length > 60 ? prompt.slice(0, 57) + '...' : prompt;\nconst bookmarks = [];\nfor (let i = 0; i < images.length; i++) {\n  const im = images[i];\n  const file = String(im.url.split('?')[0].split('/').pop() || '').replace(/\\.[a-z0-9]+$/i, '');\n  const tag = file ? file.slice(0, 32) : String(i + 1);\n  try {\n    const r = await propose.entity({\n      profileSlug: 'bookmark',\n      title: 'AI image: ' + shortPrompt + ' #' + tag,\n      properties: { url: im.url, prompt, model, provenance: 'connector', provider: 'fal.ai', width: im.width ?? null, height: im.height ?? null, imageCount: images.length, imageIndex: i + 1, seed: outSeed, referenceUrls: imageUrls.length ? imageUrls : null, referencePodFiles: podImages.length || null },\n      reasoning: 'Recorded the fal.ai-generated image so it is findable in the pod.'\n    });\n    bookmarks.push({ url: im.url, status: r?.status ?? 'unknown', proposalId: r?.proposalId ?? null, entityId: r?.proposedEntityId ?? null });\n  } catch (err) {\n    bookmarks.push({ url: im.url, status: 'failed', error: String(err?.message ?? err).slice(0, 300) });\n  }\n}\nconst bookmarkFailures = bookmarks.filter((b) => b.status === 'failed').length;\nreturn { success: true, proposed: false, imageUrl: urls[0], imageUrls: urls, model, prompt, imageCount: urls.length, seed: outSeed, bookmarks, bookmarkFailures };"
+      }
+    ],
+    "provides": [
+      "generate_media"
+    ]
+  },
+  "dependencies": []
+}