@synap-core/workspace-templates 0.11.0 → 0.23.0

package/capabilities/fal-media-lab.capability.json

@@ -0,0 +1,158 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "fal-media-lab",
+    "name": "fal.ai — Media Lab",
+    "description": "Create and edit images with Nano Banana 2 and turn images into video with Seedance 2. Each output is saved as a bookmark with its prompt and model after approval. fal-hosted links can expire, so keep what you need. Needs a fal.ai API key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "fal-media-lab",
+    "name": "Media Lab — fal.ai",
+    "description": "A governed generative-media workbench backed by one fal.ai API key. It creates and reference-edits images with Nano Banana 2, submits Seedance 2 image-to-video jobs to fal's durable queue, and records each request or finished provider-hosted output as a proposal-gated bookmark with prompt, model, role and provenance. This is deliberately a Phase 1 connector: it does not download media into pod-owned storage, transcode derivatives, receive webhooks automatically, or provision third-party 3D providers such as Tripo. fal output URLs can expire; retain approved media in owned storage before relying on it in production.",
+    "params": [
+      {
+        "name": "falApiKey",
+        "label": "fal.ai API key",
+        "type": "text",
+        "required": true,
+        "description": "A fal.ai API key from https://fal.ai/dashboard/keys. It is encrypted in this pod's vault and is never included in generated media records."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "falApiKeySecret",
+        "name": "{{name}} fal.ai API key",
+        "value": "{{falApiKey}}",
+        "type": "api_key",
+        "description": "Credential for the Media Lab's fal.run and queue.fal.run tools."
+      }
+    ],
+    "tools": [
+      {
+        "name": "fal_media_run",
+        "kind": "api",
+        "description": "Authenticated access to fal.ai's synchronous model API. Use for Nano Banana 2 image generation and reference-image editing.",
+        "credentialRef": "falApiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://fal.run",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Key "
+          }
+        }
+      },
+      {
+        "name": "fal_media_queue",
+        "kind": "api",
+        "description": "Authenticated access to fal.ai's persistent queue API. Use for asynchronous Seedance 2 video submission, status and result retrieval.",
+        "credentialRef": "falApiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://queue.fal.run",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Key "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "fal_generate_art_directed_image",
+        "intent": "generate_media",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Generate an art-directed still with fal.ai Nano Banana 2, then propose the provider-hosted output as a media bookmark. Args: { prompt: string, aspectRatio?: string, resolution?: string, role?: string }. Use a role such as hero, transition, background, texture or reference so the record remains useful later.",
+        "requires": [
+          "fal_media_run"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 120,
+        "parameters": {
+          "prompt": "string",
+          "aspectRatio": "string?",
+          "resolution": "string?",
+          "role": "string?"
+        },
+        "code": "const prompt = String(args?.prompt ?? '').trim();\nif (!prompt) throw new Error('fal_generate_art_directed_image: prompt is required');\nconst aspectRatio = String(args?.aspectRatio ?? 'auto').trim() || 'auto';\nconst resolution = String(args?.resolution ?? '1K').trim() || '1K';\nconst role = String(args?.role ?? 'reference').trim() || 'reference';\nconst res = await callProvider('fal_media_run', 'POST', '/fal-ai/nano-banana-2', { prompt, num_images: 1, aspect_ratio: aspectRatio, output_format: 'png', resolution, limit_generations: true, enable_web_search: false });\nif (res?.proposed === true) return { success: false, proposed: true, proposalId: res?.proposalId ?? null, prompt };\nconst ok = typeof res?.status === 'number' && res.status >= 200 && res.status < 300;\nconst body = res?.body ?? res;\nconst image = Array.isArray(body?.images) ? body.images[0] : null;\nconst imageUrl = image?.url ?? null;\nif (!ok || !imageUrl) throw new Error('fal_generate_art_directed_image: generation failed or returned no image (status ' + (res?.status ?? 'unknown') + ')');\nawait propose.entity({ profileSlug: 'bookmark', title: 'Media image: ' + (prompt.length > 76 ? prompt.slice(0, 73) + '...' : prompt), properties: { url: imageUrl, mediaType: 'image', mediaRole: role, prompt, model: 'fal-ai/nano-banana-2', provenance: 'connector', provider: 'fal.ai', providerHosted: true, contentType: image?.content_type ?? 'image/png' }, reasoning: 'Recorded the generated image with its prompt, role and provider provenance for review.' });\nreturn { success: true, proposed: false, imageUrl, prompt, role, model: 'fal-ai/nano-banana-2' };"
+      },
+      {
+        "name": "fal_edit_reference_image",
+        "intent": "generate_media",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Edit one or more public reference-image URLs with Nano Banana 2, then propose the result as a media bookmark. Args: { prompt: string, imageUrls?: string, images?: pod file entity ids (signed by the pod at run time), aspectRatio?: string, resolution?: string, role?: string }. imageUrls is a comma- or newline-separated list of public image URLs; give at least one image through imageUrls or images; preserve a real reference and change one controlled variable at a time.",
+        "requires": [
+          "fal_media_run"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 120,
+        "parameters": {
+          "prompt": "string",
+          "imageUrls": "string?",
+          "images": "file[]:url?",
+          "aspectRatio": "string?",
+          "resolution": "string?",
+          "role": "string?"
+        },
+        "code": "const prompt = String(args?.prompt ?? '').trim();\nif (!prompt) throw new Error('fal_edit_reference_image: prompt is required');\nconst imageUrls = String(args?.imageUrls ?? '').split(/[\\n,]/).map((value) => value.trim()).filter((value) => /^https?:\\/\\//.test(value));\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_edit_reference_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_edit_reference_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 === 0) throw new Error('fal_edit_reference_image: give at least one reference image: imageUrls (public http(s) URLs) or images (pod file ids)');\nconst aspectRatio = String(args?.aspectRatio ?? 'auto').trim() || 'auto';\nconst resolution = String(args?.resolution ?? '1K').trim() || '1K';\nconst role = String(args?.role ?? 'reference').trim() || 'reference';\nconst res = await callProvider('fal_media_run', 'POST', '/fal-ai/nano-banana-2/edit', { prompt, image_urls: references.slice(0, 8), num_images: 1, aspect_ratio: aspectRatio, output_format: 'png', resolution, limit_generations: true, enable_web_search: false });\nif (res?.proposed === true) return { success: false, proposed: true, proposalId: res?.proposalId ?? null, prompt };\nconst ok = typeof res?.status === 'number' && res.status >= 200 && res.status < 300;\nconst body = res?.body ?? res;\nconst image = Array.isArray(body?.images) ? body.images[0] : null;\nconst imageUrl = image?.url ?? null;\nif (!ok || !imageUrl) throw new Error('fal_edit_reference_image: edit failed or returned no image (status ' + (res?.status ?? 'unknown') + ')');\nawait propose.entity({ profileSlug: 'bookmark', title: 'Media edit: ' + (prompt.length > 78 ? prompt.slice(0, 75) + '...' : prompt), properties: { url: imageUrl, mediaType: 'image', mediaRole: role, prompt, model: 'fal-ai/nano-banana-2/edit', provenance: 'connector', provider: 'fal.ai', providerHosted: true, referenceUrls: imageUrls, referencePodFiles: podImages.length || null, contentType: image?.content_type ?? 'image/png' }, reasoning: 'Recorded the reference-image edit with its source URLs and prompt for review.' });\nreturn { success: true, proposed: false, imageUrl, prompt, role, referenceUrls: imageUrls, referencePodFiles: podImages.length, model: 'fal-ai/nano-banana-2/edit' };"
+      },
+      {
+        "name": "fal_submit_seedance_video",
+        "intent": "generate_media",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Submit a Seedance 2 image-to-video job to fal.ai's durable queue and propose a pending job record. Args: { prompt: string, imageUrl?: string OR image?: a pod file entity id (the first frame; exactly one), endImageUrl?: string OR endImage?: a pod file entity id (the pod signs pod files at run time), duration?: string, aspectRatio?: string, resolution?: string, role?: string, generateAudio?: string }. Then use fal_record_seedance_video with the returned requestId once the queue completes.",
+        "requires": [
+          "fal_media_queue"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "prompt": "string",
+          "imageUrl": "string?",
+          "image": "file:url?",
+          "endImageUrl": "string?",
+          "endImage": "file:url?",
+          "duration": "string?",
+          "aspectRatio": "string?",
+          "resolution": "string?",
+          "role": "string?",
+          "generateAudio": "string?"
+        },
+        "code": "const prompt = String(args?.prompt ?? '').trim();\nconst imageUrl = String(args?.imageUrl ?? '').trim();\nif (!prompt) throw new Error('fal_submit_seedance_video: prompt is required');\n// image / endImage are POD FILES (declared \"file:url?\", backend #469): the pod\n// swaps each file entity id for a fresh signed URL at run time (6 h for this\n// async verb, so the queue can fetch it later). Never stored or echoed.\nconst SIGNED = /^https:\\/\\/[^\\s\\/?#@]+([\\/?#][^\\s]*)?$/i;\nconst podFile = (key) => {\n  const v = args?.[key] === undefined || args?.[key] === null ? '' : String(args[key]).trim();\n  if (v && (v.length > 4096 || !SIGNED.test(v))) throw new Error('fal_submit_seedance_video: ' + key + ' did not arrive as a signed pod file URL; pass a pod file entity id');\n  return v;\n};\nconst image = podFile('image');\nconst endImage = podFile('endImage');\nif (imageUrl && image) throw new Error('fal_submit_seedance_video: pass imageUrl or image, not both');\nif (!imageUrl && !image) throw new Error('fal_submit_seedance_video: the first frame is required: imageUrl (a public http(s) URL) or image (a pod file id)');\nif (imageUrl && !/^https?:\\/\\//.test(imageUrl)) throw new Error('fal_submit_seedance_video: imageUrl must be a public http(s) URL');\nconst endImageUrl = String(args?.endImageUrl ?? '').trim();\nif (endImageUrl && endImage) throw new Error('fal_submit_seedance_video: pass endImageUrl or endImage, not both');\nif (endImageUrl && !/^https?:\\/\\//.test(endImageUrl)) throw new Error('fal_submit_seedance_video: endImageUrl must be a public http(s) URL when provided');\nconst duration = String(args?.duration ?? 'auto').trim() || 'auto';\nconst aspectRatio = String(args?.aspectRatio ?? 'auto').trim() || 'auto';\nconst resolution = String(args?.resolution ?? '720p').trim() || '720p';\nconst role = String(args?.role ?? 'transition').trim() || 'transition';\nconst generateAudio = String(args?.generateAudio ?? 'true').trim().toLowerCase() !== 'false';\nconst payload = { prompt, image_url: imageUrl || image, duration, aspect_ratio: aspectRatio, resolution, generate_audio: generateAudio, bitrate_mode: 'high' };\nif (endImageUrl || endImage) payload.end_image_url = endImageUrl || endImage;\nconst res = await callProvider('fal_media_queue', 'POST', '/bytedance/seedance-2.0/image-to-video', payload);\nif (res?.proposed === true) return { success: false, proposed: true, proposalId: res?.proposalId ?? null, prompt };\nconst ok = typeof res?.status === 'number' && res.status >= 200 && res.status < 300;\nconst body = res?.body ?? res;\nconst requestId = body?.request_id ?? null;\nconst statusUrl = body?.status_url ?? null;\nconst responseUrl = body?.response_url ?? null;\nif (!ok || !requestId) throw new Error('fal_submit_seedance_video: queue submission failed or returned no request_id (status ' + (res?.status ?? 'unknown') + ')');\nawait propose.entity({ profileSlug: 'bookmark', title: 'Media video job: ' + (prompt.length > 72 ? prompt.slice(0, 69) + '...' : prompt), properties: { url: statusUrl ?? responseUrl ?? 'https://queue.fal.run/bytedance/seedance-2.0/image-to-video/requests/' + encodeURIComponent(requestId) + '/status', mediaType: 'video-job', mediaRole: role, prompt, model: 'bytedance/seedance-2.0/image-to-video', provenance: 'connector', provider: 'fal.ai', requestId, status: 'IN_QUEUE', imageUrl: imageUrl || null, endImageUrl: endImageUrl || null, imageFromPod: !!image, endImageFromPod: !!endImage, duration, aspectRatio, resolution, generateAudio, providerHosted: true }, reasoning: 'Recorded the queued Seedance video request so its status and final result can be reviewed later.' });\nreturn { success: true, proposed: false, requestId, statusUrl, responseUrl, prompt, role, model: 'bytedance/seedance-2.0/image-to-video' };"
+      },
+      {
+        "name": "fal_record_seedance_video",
+        "intent": "capture_into_pod",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Check a Seedance 2 queue request and, only when complete, propose its provider-hosted video as a media bookmark. Args: { requestId: string, role?: string }. If the result is still queued or running, it returns status without creating a duplicate record.",
+        "requires": [
+          "fal_media_queue"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "requestId": "string",
+          "role": "string?"
+        },
+        "code": "const requestId = String(args?.requestId ?? '').trim();\nif (!requestId) throw new Error('fal_record_seedance_video: requestId is required');\nconst role = String(args?.role ?? 'transition').trim() || 'transition';\nconst modelPath = '/bytedance/seedance-2.0/image-to-video/requests/' + encodeURIComponent(requestId);\nconst statusRes = await callProvider('fal_media_queue', 'GET', modelPath + '/status?logs=1');\nif (statusRes?.proposed === true) return { success: false, proposed: true, proposalId: statusRes?.proposalId ?? null, requestId };\nconst statusOk = typeof statusRes?.status === 'number' && statusRes.status >= 200 && statusRes.status < 300;\nconst statusBody = statusRes?.body ?? statusRes;\nif (!statusOk) throw new Error('fal_record_seedance_video: status lookup failed (status ' + (statusRes?.status ?? 'unknown') + ')');\nif (statusBody?.status !== 'COMPLETED') return { success: true, complete: false, requestId, status: statusBody?.status ?? 'UNKNOWN', queuePosition: statusBody?.queue_position ?? null, error: statusBody?.error ?? null };\nif (statusBody?.error) throw new Error('fal_record_seedance_video: fal completed with error: ' + statusBody.error);\nconst resultRes = await callProvider('fal_media_queue', 'GET', modelPath);\nconst resultOk = typeof resultRes?.status === 'number' && resultRes.status >= 200 && resultRes.status < 300;\nconst body = resultRes?.body ?? resultRes;\nconst video = body?.video ?? null;\nconst videoUrl = video?.url ?? null;\nif (!resultOk || !videoUrl) throw new Error('fal_record_seedance_video: completed request returned no video (status ' + (resultRes?.status ?? 'unknown') + ')');\nawait propose.entity({ profileSlug: 'bookmark', title: 'Media video: Seedance ' + requestId.slice(0, 8), properties: { url: videoUrl, mediaType: 'video', mediaRole: role, model: 'bytedance/seedance-2.0/image-to-video', provenance: 'connector', provider: 'fal.ai', requestId, seed: body?.seed ?? null, providerHosted: true, contentType: video?.content_type ?? 'video/mp4', fileName: video?.file_name ?? null, fileSize: video?.file_size ?? null }, reasoning: 'Recorded the completed Seedance video with its model, request ID and provider provenance for review.' });\nreturn { success: true, complete: true, proposed: false, requestId, videoUrl, role, seed: body?.seed ?? null, model: 'bytedance/seedance-2.0/image-to-video' };"
+      }
+    ],
+    "provides": [
+      "generate_media",
+      "capture_into_pod"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/fireflies.capability.json

@@ -0,0 +1,191 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "fireflies",
+    "name": "Fireflies.ai Meetings",
+    "description": "Search and read your Fireflies.ai transcripts, and import a meeting as a summary note, attendees and action-item tasks after your approval. New transcripts can also arrive automatically. Needs a Fireflies API key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "fireflies",
+    "name": "Fireflies.ai Meetings",
+    "description": "Import Fireflies.ai meeting recordings into Synap as an entity graph. Fireflies exposes a single GraphQL endpoint (https://api.fireflies.ai/graphql) authenticated with `Authorization: Bearer <key>`. Stores the API key in the vault, registers one HTTP API tool (vault-generic) whose baseUrl IS the GraphQL endpoint, and seeds skills: DECLARATIVE GraphQL read verbs (fireflies_search, fireflies_get_transcript, fireflies_list_recent_transcripts) and a proposal-gated code import skill. The declarative verbs use the `transport:\"graphql\"` provider-verb shape (POST { query, variables } to the /graphql path, unwrap `data`, surface `errors[]` as a provider error) — no hand-rolled payload.errors/payload.data boilerplate. The import skill stays a code skill because it orchestrates an ENTITY-GRAPH proposal (a note for the summary + a person per attendee + a task per action item) that a declarative HTTP verb cannot express. The applier remaps the tool's template-local vault ref to a runtime vault://<id>, and the dispatcher resolves the tool by NAME server-side and injects the vaulted key as the Bearer token. PRECONDITION: a Fireflies API key (Fireflies dashboard -> Settings -> Developer Settings -> API Key). Pass it as `firefliesApiKey`. INBOUND WEBHOOK (transcripts -> channel/message substrate): Fireflies fires a single `Transcription complete` event with a minimal payload {meetingId, eventType, clientReferenceId} to POST /api/webhooks/fireflies/:token; the pod verifies it, enqueues a fetch-then-ingest job that calls fireflies_get_transcript and lands the transcript as a channel MESSAGE via recordInboundMessage (queryable by the AI). fireflies_list_recent_transcripts backs a backfill poller that recovers missed webhooks. The webhook config is provisioned at install/config time (NOT template-seeded) under `tools.metadata.fireflies.webhook = { token, secretVaultRef?, workspaceId?, ownerUserId?, seen:{} }` and backfill under `tools.metadata.fireflies.backfill = { enabled }`; the `:token` selects+authorizes the config (unknown -> 404), and when `secretVaultRef` is set the `x-hub-signature` header (SHA-256 HMAC of the raw body, `sha256=<hex>`, vault-resolved secret) is verified fail-closed.",
+    "params": [
+      {
+        "name": "firefliesApiKey",
+        "label": "Fireflies API key",
+        "type": "text",
+        "required": true,
+        "description": "The Fireflies.ai API key (dashboard -> Settings -> Developer Settings -> API Key). Used as the Bearer token. Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "firefliesApiKeySecret",
+        "name": "{{name}} Fireflies API key",
+        "value": "{{firefliesApiKey}}",
+        "type": "api_key",
+        "description": "Fireflies.ai API key (Bearer token) for the fireflies connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "fireflies",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the Fireflies.ai GraphQL API. The applier injects the vaulted API key into the Authorization header as `Bearer <key>`; its credentialRef is remapped to the runtime vault://<id> at apply time. baseUrl IS the single GraphQL endpoint — skills POST { query, variables } with an empty path.",
+        "credentialRef": "firefliesApiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.fireflies.ai",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "fireflies_import_last_meeting",
+        "intent": "capture_into_pod",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Imports the most recent Fireflies meeting and proposes the full entity graph (proposal-gated): a note for the meeting summary, a person per attendee (deduped by email), and a task per action item. No args. Returns { success, meetingTitle, attendees, actionItems }.",
+        "requires": [
+          "fireflies"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 90,
+        "parameters": {},
+        "code": "// Import the most recent Fireflies meeting and propose the entity graph.\n// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return` the result. callProvider(tool, method, path, body?)\n// runs the required tool ('fireflies') through the dispatcher: it injects the\n// vaulted API key as Authorization: Bearer <key> and POSTs to the tool's\n// config.baseUrl (= https://api.fireflies.ai/graphql). Path is EMPTY because the\n// baseUrl IS the single GraphQL endpoint; the body is { query, variables }.\nconst gql = async (query, variables) => {\n  const res = await callProvider('fireflies', 'POST', '/graphql', { query: query, variables: variables || {} });\n  const payload = res && res.body !== undefined ? res.body : res;\n  if (payload && Array.isArray(payload.errors) && payload.errors.length) {\n    throw new Error('Fireflies GraphQL error: ' + String((payload.errors[0] && payload.errors[0].message) || 'unknown'));\n  }\n  return (payload && payload.data) || {};\n};\n\n// 1) Most recent transcript id.\nconst listData = await gql('query { transcripts(mine: true, limit: 1) { id } }');\nconst list = (listData && Array.isArray(listData.transcripts)) ? listData.transcripts : [];\nif (!list.length) return { success: false, reason: 'no transcripts found' };\nconst transcriptId = String((list[0] && list[0].id) || '');\nif (!transcriptId) return { success: false, reason: 'most recent transcript has no id' };\n\n// 2) Full transcript detail.\nconst detailData = await gql(\n  'query Transcript($id: String!) { transcript(id: $id) { id title date duration meeting_link transcript_url meeting_attendees { name email } summary { overview action_items keywords topics_discussed } } }',\n  { id: transcriptId }\n);\nconst t = (detailData && detailData.transcript) || {};\nconst title = String(t.title || 'Untitled meeting');\nconst summary = (t.summary && typeof t.summary === 'object') ? t.summary : {};\nconst overview = String(summary.overview || '');\n\n// Meeting summary -> note.\nawait propose.entity({\n  profileSlug: 'note',\n  title: title,\n  properties: {\n    date: t.date != null ? String(t.date) : null,\n    durationMin: t.duration != null ? Number(t.duration) : null,\n    meetingLink: t.meeting_link != null ? String(t.meeting_link) : null,\n    provenance: 'connector', provider: 'fireflies',\n    firefliesId: String(t.id || transcriptId),\n    summary: overview,\n    transcriptUrl: t.transcript_url != null ? String(t.transcript_url) : null\n  },\n  reasoning: 'Imported meeting summary from Fireflies.'\n});\n\n// Attendees -> person (dedupe by email, then by lowercased name).\nconst attendees = Array.isArray(t.meeting_attendees) ? t.meeting_attendees : [];\nconst seen = {};\nlet attendeeCount = 0;\nfor (const a of attendees) {\n  const email = (a && a.email != null) ? String(a.email).trim() : '';\n  const name = (a && a.name != null) ? String(a.name).trim() : '';\n  if (!email && !name) continue;\n  const dedupeKey = email ? email.toLowerCase() : name.toLowerCase();\n  if (seen[dedupeKey]) continue;\n  seen[dedupeKey] = true;\n  await propose.entity({\n    profileSlug: 'person',\n    title: name || email,\n    properties: { email: email || null, provenance: 'connector', provider: 'fireflies' },\n    reasoning: 'Attendee of the imported Fireflies meeting: ' + title\n  });\n  attendeeCount++;\n}\n\n// action_items is ONE markdown STRING (not an array) -> split by newline.\nconst rawActions = (summary.action_items != null) ? String(summary.action_items) : '';\nconst lines = rawActions.split('\\n').map((l) => String(l).trim()).filter((l) => l.length > 0);\nlet actionCount = 0;\nfor (const line of lines) {\n  await propose.entity({\n    profileSlug: 'task',\n    title: line,\n    properties: { provenance: 'connector', provider: 'fireflies', fromMeeting: title },\n    reasoning: 'Action item extracted from the imported Fireflies meeting: ' + title\n  });\n  actionCount++;\n}\n\nreturn { success: true, meetingTitle: title, attendees: attendeeCount, actionItems: actionCount };\n"
+      },
+      {
+        "name": "fireflies_search",
+        "intent": "search_external",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Searches recent Fireflies transcripts by keyword and returns a list of { id, title, date } (read; returns inline). Args: { query: string }.",
+        "requires": [
+          "fireflies"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "query": "string"
+        },
+        "providerSpec": {
+          "tool": "fireflies",
+          "method": "POST",
+          "pathTemplate": "/graphql",
+          "transport": "graphql",
+          "graphql": {
+            "query": "query Search($keyword: String) { transcripts(mine: true, limit: 10, keyword: $keyword) { id title date } }",
+            "variables": {
+              "keyword": "{{query}}"
+            },
+            "operation": "query",
+            "dataPath": "data"
+          },
+          "responseShape": {
+            "collectionPath": "transcripts",
+            "collectionAs": "results",
+            "item": {
+              "id": "id",
+              "title": "title",
+              "date": "date"
+            },
+            "scalar": {
+              "query": "{{query}}",
+              "count": "@count"
+            }
+          }
+        }
+      },
+      {
+        "name": "fireflies_get_transcript",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Fetches ONE Fireflies transcript by id — full transcript sentences, participants, title, date, summary. Backs the inbound-webhook ingestion worker that lands a completed meeting as a channel message. Args: { id: string }. Returns { transcript, meetingId } where `transcript` is the full object (incl. sentences[] and meeting_attendees[]).",
+        "requires": [
+          "fireflies"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "id": "string"
+        },
+        "providerSpec": {
+          "tool": "fireflies",
+          "method": "POST",
+          "pathTemplate": "/graphql",
+          "transport": "graphql",
+          "graphql": {
+            "query": "query Transcript($id: String!) { transcript(id: $id) { id title date duration meeting_link transcript_url meeting_attendees { name email displayName } summary { overview action_items keywords } sentences { speaker_name text } } }",
+            "variables": {
+              "id": "{{id}}"
+            },
+            "operation": "query",
+            "dataPath": "data"
+          },
+          "responseShape": {
+            "scalar": {
+              "transcript": "transcript",
+              "meetingId": "transcript.id"
+            }
+          }
+        }
+      },
+      {
+        "name": "fireflies_list_recent_transcripts",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the most recent Fireflies transcripts (id, title, date). Backs the backfill poller that recovers meetings whose completion webhook was missed. No args. Returns { results: [{ id, title, date }], count }.",
+        "requires": [
+          "fireflies"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {},
+        "providerSpec": {
+          "tool": "fireflies",
+          "method": "POST",
+          "pathTemplate": "/graphql",
+          "transport": "graphql",
+          "graphql": {
+            "query": "query Recent { transcripts(mine: true, limit: 50) { id title date } }",
+            "variables": {},
+            "operation": "query",
+            "dataPath": "data"
+          },
+          "responseShape": {
+            "collectionPath": "transcripts",
+            "collectionAs": "results",
+            "item": {
+              "id": "id",
+              "title": "title",
+              "date": "date"
+            },
+            "scalar": {
+              "count": "@count"
+            }
+          }
+        }
+      }
+    ],
+    "provides": [
+      "capture_into_pod",
+      "search_external",
+      "fetch_record",
+      "list_records"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/freellmapi.capability.json

@@ -0,0 +1,114 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "freellmapi",
+    "name": "FreeLLMAPI Gateway",
+    "description": "Connects a self-hosted FreeLLMAPI gateway so agents can see which free-tier models are available, provider health, usage and routing. Changing the routing strategy needs your approval. Needs a running FreeLLMAPI instance and its API key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "freellmapi",
+    "name": "FreeLLMAPI — Free-Tier LLM Gateway",
+    "description": "Connects a self-hosted FreeLLMAPI gateway (pooled free-tier LLM quota behind one OpenAI-compatible endpoint) to this pod as a governed MCP server. Agents get live introspection — which models are available and tool-capable, per-provider health and cooldowns, usage, routing — as INLINE read tools. Changing the gateway's routing strategy is a WRITE and goes through review. PRECONDITION: a running FreeLLMAPI instance (e.g. `eve add freellmapi`) and its unified API key.",
+    "params": [
+      {
+        "name": "baseUrl",
+        "label": "Gateway URL",
+        "type": "text",
+        "required": true,
+        "description": "Base URL of the FreeLLMAPI gateway WITHOUT a trailing path, reachable from the intelligence service — e.g. https://llm.example.com. The MCP endpoint is <baseUrl>/mcp."
+      },
+      {
+        "name": "apiKey",
+        "label": "Unified API key",
+        "type": "text",
+        "required": true,
+        "description": "The gateway's unified key (freellmapi-…). Stored server-encrypted as a pod-wide shared key; used only as the MCP transport's Authorization header, never shown to agents."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "unifiedKey",
+        "name": "FreeLLMAPI unified key",
+        "value": "{{apiKey}}",
+        "type": "api_key",
+        "podWide": true,
+        "description": "Service credential for the FreeLLMAPI gateway's /mcp endpoint."
+      }
+    ],
+    "mcpServers": [
+      {
+        "slug": "freellmapi",
+        "name": "FreeLLMAPI",
+        "description": "Free-tier LLM gateway introspection: models, provider health and cooldowns, usage, routing, cache and compression stats.",
+        "transport": "http",
+        "url": "{{baseUrl}}/mcp",
+        "enabled": true,
+        "auth": {
+          "credentialRef": "unifiedKey",
+          "header": "Authorization",
+          "prefix": "Bearer "
+        },
+        "toolPolicy": {
+          "default": "governed",
+          "inline": [
+            "list_models",
+            "provider_health",
+            "usage_summary",
+            "routing_info",
+            "cache_stats",
+            "compression_stats"
+          ]
+        },
+        "metadata": {
+          "provider": "freellmapi",
+          "docs": "https://github.com/tashfeenahmed/freellmapi",
+          "note": "Allowlist of READS, default governed: a write tool added upstream is gated automatically rather than silently inline."
+        }
+      }
+    ],
+    "tools": [
+      {
+        "name": "freellmapi_mcp",
+        "kind": "mcp",
+        "description": "Governed gateway to the FreeLLMAPI MCP server. The pod routes an agent's call to a non-inline tool (set_routing_strategy) through this row, where the capability gate turns it into a proposal. Path = MCP tool name; body = tool arguments.",
+        "credentialRef": "mcp://freellmapi",
+        "executor": "is-agent",
+        "config": {
+          "serverSlug": "freellmapi"
+        },
+        "metadata": {
+          "provider": "freellmapi",
+          "mcpTools": [
+            "list_models",
+            "provider_health",
+            "usage_summary",
+            "routing_info",
+            "cache_stats",
+            "compression_stats",
+            "set_routing_strategy"
+          ],
+          "governedTools": [
+            "set_routing_strategy"
+          ]
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "freellmapi-gateway-advisor",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "When and how to use the FreeLLMAPI gateway's MCP tools. Load when a model/provider choice depends on free-tier availability, a provider looks rate-limited, or the user asks about LLM usage or cost.",
+        "code": "# FreeLLMAPI gateway\n\nFreeLLMAPI pools free-tier quota from many providers behind one OpenAI-compatible endpoint. On this pod it is registered as a LOW-PRIORITY fallback provider, so it serves turns only when paid providers fail.\n\n## Read tools (run immediately)\n\n| Tool | Use |\n|---|---|\n| `list_models` | Which models the router can serve, context windows, and which support tool calls |\n| `provider_health` | Per-provider key status (healthy / rate_limited / invalid), active cooldowns |\n| `usage_summary` | Requests, tokens, success rate over 24h / 7d / 30d |\n| `routing_info` | Current routing strategy and top-scored models |\n| `cache_stats` / `compression_stats` | Token savings |\n\n## Write tool (needs the user's approval)\n\n`set_routing_strategy` — one of `priority`, `balanced`, `smartest`, `fastest`, `reliable`, `custom`. Calling it files a proposal; it changes nothing until approved. Say what you proposed and why; do not retry it.\n\n## Rules\n- Check `provider_health` before blaming a model for a failure.\n- Never claim a model supports tools without `list_models` saying so.\n- Report numbers from `usage_summary` as measured, with the window."
+      }
+    ],
+    "provides": []
+  },
+  "dependencies": []
+}

package/capabilities/generic-apikey.capability.json

@@ -0,0 +1,92 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "generic-apikey",
+    "name": "Custom API Connector (template)",
+    "description": "A starting point for connecting any API that uses an API key: stores the key, registers the API and adds a skill that fetches records and proposes them as entities. Set the base URL, key and target entity type when you install.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "generic-apikey",
+    "name": "Generic API-Key Connector",
+    "description": "Provider-neutral demonstration of the capability-template shape: stores one API key in the vault, registers one HTTP API tool that authenticates with it, and seeds one code skill that fetches from the provider and proposes the results as entities. Customize via the {{baseUrl}}, {{apiKey}}, and {{entityProfile}} params — no provider is hardcoded.",
+    "params": [
+      {
+        "name": "apiKey",
+        "label": "API key",
+        "type": "text",
+        "required": true,
+        "description": "The bearer API key for the provider. Stored server-encrypted in the vault; never persisted in the template."
+      },
+      {
+        "name": "baseUrl",
+        "label": "Base URL",
+        "type": "text",
+        "required": true,
+        "description": "The provider's API base URL, e.g. https://api.example.com/v1"
+      },
+      {
+        "name": "entityProfile",
+        "label": "Target entity profile",
+        "type": "text",
+        "required": false,
+        "default": "note",
+        "description": "The profileSlug the skill proposes fetched records as."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "apiKeySecret",
+        "name": "{{name}} API key",
+        "value": "{{apiKey}}",
+        "type": "api_key",
+        "description": "API key for the generic-apikey connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "generic_api",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the provider API.",
+        "credentialRef": "apiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "{{baseUrl}}",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "{{name}} fetch-and-propose",
+        "intent": "capture_into_pod",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Fetches records from the provider API and proposes each as an entity (proposal-gated). Calls the required tool by name via callProvider('generic_api', ...).",
+        "requires": [
+          "generic_api"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "path": "string?",
+          "entityProfile": "string?"
+        },
+        "code": "// Generic fetch -> propose loop. The skill body is a STATEMENT body (no `export\n// default`); the executor wraps it as (async function(args, context){ <code> }).\n// callProvider is POSITIONAL: callProvider(provider, method, path, body?) where\n// `provider` is the required tool's NAME ('generic_api') — the dispatcher resolves\n// it to the tool's credentialRef server-side and injects the vaulted API key. No\n// providerRef arg needed. propose.entity REQUIRES `title` (not `name`) and routes\n// the write through checkPermissionOrPropose.\nconst path = args.path || '/records';\nconst profileSlug = args.entityProfile || 'note';\nconst res = await callProvider('generic_api', 'GET', path);\nconst data = res && res.body !== undefined ? res.body : res;\nconst records = Array.isArray(data)\n  ? data\n  : (data && Array.isArray(data.data) ? data.data : (data && data.records) || []);\nlet proposed = 0;\nfor (const record of records) {\n  await propose.entity({\n    profileSlug,\n    title: String((record && (record.name || record.title || record.id)) || 'record'),\n    properties: record,\n  });\n  proposed++;\n}\nreturn { proposed };\n"
+      }
+    ],
+    "provides": [
+      "capture_into_pod"
+    ]
+  },
+  "dependencies": []
+}