@synap-core/workspace-templates 0.12.0 → 0.23.0

package/capabilities/notion.capability.json

@@ -0,0 +1,417 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "notion",
+    "name": "Notion — Workspace & Knowledge",
+    "description": "Notion workspace operations through one Nango OAuth connection (Notion REST API): search pages and databases, read/create pages, list and query databases, and read/append block children. Search and query default their page size (max 100). Connect your Notion account to use it.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "notion",
+    "name": "Notion — Workspace & Knowledge",
+    "description": "Notion workspace operations through ONE Nango OAuth connection (Notion REST API v1). Search the pages and databases a user has shared with the integration; read a page's properties, a database's schema, or a page/block's children; and create pages or append text blocks. PRECONDITION: the 'notion' integration must be declared + configured on the pod's Nango with base URL https://api.notion.com, and the acting user must connect their Notion account via Connectors; the dispatcher resolves the most-recent notion connection automatically. SCOPES: Notion OAuth is capability-based, not scope-string-based — at connect time the user picks which pages/databases to grant, and the integration receives read + insert + update content access to exactly those (Notion 'Read content' / 'Insert content' / 'Update content'). Paths are RELATIVE to the Nango notion integration's base URL (https://api.notion.com) — no baseUrlOverride, so no provider-proxy-host allowlist entry is needed. Every call sends the required header Notion-Version: 2022-06-28. READS (GET, POST /v1/search, POST .../query) return data inline and auto-run; WRITES (POST /v1/pages, PATCH /v1/blocks/{id}/children) are side-effecting and route through the capability-execution gate. CAVEATS: (1) the Notion REST API PINNED here is 2022-06-28 — newer Notion-Versions rename databases to 'data sources' and move query/retrieve to /v1/data_sources/{id}/query, so changing the header changes these paths; (2) the pod's declarative body interpolation emits every interpolated value as a JSON STRING, so a numeric body field (page_size on the POST endpoints) is sent as \"25\" — verify at first run and, if Notion rejects it, either hardcode the literal or move that verb to kind:'code'; (3) response-field shaping is best-effort and confirmed against the live API at first run.",
+    "params": [],
+    "vault": [],
+    "tools": [
+      {
+        "name": "notion",
+        "kind": "provider",
+        "description": "Notion REST API access through Nango. credentialRef nango://notion resolves the user's Notion OAuth connection (Connection-Id + Provider-Config-Key) and proxies to the integration's base URL (https://api.notion.com). Every call sends Notion-Version: 2022-06-28.",
+        "credentialRef": "nango://notion",
+        "executor": "is-agent",
+        "config": {
+          "providerConfigKey": "notion"
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "notion_search",
+        "intent": "search_external",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Searches the user's Notion workspace by title across pages AND databases (most recently edited first). Returns raw page/database objects under `results`. Args: { query: string }. NOTE: page size is hardcoded to 25 in the request body (Notion accepts page_size as a number, but the declarative engine stringifies every interpolated value, so the param cannot be passed through). Use notion_query_database with its cursor for pagination.",
+        "requires": [
+          "notion"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "query": "string"
+        },
+        "providerSpec": {
+          "tool": "notion",
+          "method": "POST",
+          "pathTemplate": "/v1/search",
+          "headers": {
+            "Notion-Version": "2022-06-28"
+          },
+          "body": {
+            "query": "{{query}}",
+            "page_size": 25
+          },
+          "paramMapping": {
+            "query": {
+              "required": true
+            }
+          },
+          "responseShape": {
+            "collectionPath": "results",
+            "collectionAs": "results",
+            "scalar": {
+              "count": "@count",
+              "nextCursor": "next_cursor",
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "notion_get_page",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Gets one page by id — its property values, parent, url and timestamps. Args: { pageId: string }.",
+        "requires": [
+          "notion"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "pageId": "string"
+        },
+        "providerSpec": {
+          "tool": "notion",
+          "method": "GET",
+          "pathTemplate": "/v1/pages/{{pageId}}",
+          "headers": {
+            "Notion-Version": "2022-06-28"
+          },
+          "paramMapping": {
+            "pageId": {
+              "required": true,
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "id": "id",
+              "object": "object",
+              "url": "url",
+              "createdTime": "created_time",
+              "lastEdited": "last_edited_time",
+              "archived": "archived",
+              "parentType": "parent.type",
+              "properties": "properties"
+            }
+          }
+        }
+      },
+      {
+        "name": "notion_create_page",
+        "intent": "manage_file",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Creates a new page as a CHILD of a parent page, with the given title. Side-effecting write — routes through the capability-execution gate. Args: { parent: string (parent PAGE id), title: string }.",
+        "requires": [
+          "notion"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "parent": "string",
+          "title": "string"
+        },
+        "providerSpec": {
+          "tool": "notion",
+          "method": "POST",
+          "pathTemplate": "/v1/pages",
+          "headers": {
+            "Notion-Version": "2022-06-28"
+          },
+          "body": {
+            "parent": {
+              "page_id": "{{parent}}"
+            },
+            "properties": {
+              "title": {
+                "title": [
+                  {
+                    "type": "text",
+                    "text": {
+                      "content": "{{title}}"
+                    }
+                  }
+                ]
+              }
+            }
+          },
+          "paramMapping": {
+            "parent": {
+              "required": true
+            },
+            "title": {
+              "required": true
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "id": "id",
+              "object": "object",
+              "url": "url",
+              "createdTime": "created_time"
+            }
+          }
+        }
+      },
+      {
+        "name": "notion_list_databases",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the databases the user has granted access to, each with its title and url (search filtered to databases). Args: {}. NOTE: page size is hardcoded to 25 in the request body (Notion accepts page_size as a number, but the declarative engine stringifies every interpolated value, so the param cannot be passed through).",
+        "requires": [
+          "notion"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {},
+        "providerSpec": {
+          "tool": "notion",
+          "method": "POST",
+          "pathTemplate": "/v1/search",
+          "headers": {
+            "Notion-Version": "2022-06-28"
+          },
+          "body": {
+            "filter": {
+              "property": "object",
+              "value": "database"
+            },
+            "page_size": 25
+          },
+          "paramMapping": {},
+          "responseShape": {
+            "collectionPath": "results",
+            "collectionAs": "databases",
+            "item": {
+              "id": "id",
+              "title": "title.0.plain_text",
+              "url": "url",
+              "createdTime": "created_time",
+              "lastEdited": "last_edited_time"
+            },
+            "scalar": {
+              "count": "@count",
+              "nextCursor": "next_cursor",
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "notion_query_database",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Queries a database and returns its rows (pages). Each row carries its raw `properties` so any column can be read (the title column's name varies per database). Args: { databaseId: string }. NOTE: page size is hardcoded to 25 in the request body (Notion accepts page_size as a number, but the declarative engine stringifies every interpolated value, so the param cannot be passed through). Use the response's nextCursor to page through results.",
+        "requires": [
+          "notion"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "databaseId": "string"
+        },
+        "providerSpec": {
+          "tool": "notion",
+          "method": "POST",
+          "pathTemplate": "/v1/databases/{{databaseId}}/query",
+          "headers": {
+            "Notion-Version": "2022-06-28"
+          },
+          "body": {
+            "page_size": 25
+          },
+          "paramMapping": {
+            "databaseId": {
+              "required": true,
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "collectionPath": "results",
+            "collectionAs": "rows",
+            "item": {
+              "id": "id",
+              "url": "url",
+              "createdTime": "created_time",
+              "lastEdited": "last_edited_time",
+              "archived": "archived",
+              "properties": "properties"
+            },
+            "scalar": {
+              "count": "@count",
+              "nextCursor": "next_cursor",
+              "hasMore": "has_more",
+              "databaseId": "{{databaseId}}"
+            }
+          }
+        }
+      },
+      {
+        "name": "notion_get_database",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Gets one database's metadata AND schema — `properties` holds the field definitions a row must supply. Args: { databaseId: string }.",
+        "requires": [
+          "notion"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "databaseId": "string"
+        },
+        "providerSpec": {
+          "tool": "notion",
+          "method": "GET",
+          "pathTemplate": "/v1/databases/{{databaseId}}",
+          "headers": {
+            "Notion-Version": "2022-06-28"
+          },
+          "paramMapping": {
+            "databaseId": {
+              "required": true,
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "id": "id",
+              "object": "object",
+              "title": "title.0.plain_text",
+              "url": "url",
+              "createdTime": "created_time",
+              "lastEdited": "last_edited_time",
+              "properties": "properties"
+            }
+          }
+        }
+      },
+      {
+        "name": "notion_get_block_children",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the child blocks of a page or block (raw block objects — a block's text lives under its own type key, e.g. paragraph.rich_text[].plain_text). Args: { blockId: string (a page id or block id), page_size?: number (default 100, max 100) }.",
+        "requires": [
+          "notion"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "blockId": "string"
+        },
+        "providerSpec": {
+          "tool": "notion",
+          "method": "GET",
+          "pathTemplate": "/v1/blocks/{{blockId}}/children",
+          "headers": {
+            "Notion-Version": "2022-06-28"
+          },
+          "query": {
+            "page_size": 25
+          },
+          "paramMapping": {
+            "blockId": {
+              "required": true,
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "collectionPath": "results",
+            "collectionAs": "blocks",
+            "scalar": {
+              "count": "@count",
+              "nextCursor": "next_cursor",
+              "hasMore": "has_more",
+              "blockId": "{{blockId}}"
+            }
+          }
+        }
+      },
+      {
+        "name": "notion_append_block_children",
+        "intent": "manage_file",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Appends a paragraph of text as a new child block under a page or block. Side-effecting write — routes through the capability-execution gate. Args: { blockId: string (parent page or block id), text: string }. NOTE: appends ONE paragraph block (a single rich-text run); richer block types need a code skill.",
+        "requires": [
+          "notion"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "blockId": "string",
+          "text": "string"
+        },
+        "providerSpec": {
+          "tool": "notion",
+          "method": "PATCH",
+          "pathTemplate": "/v1/blocks/{{blockId}}/children",
+          "headers": {
+            "Notion-Version": "2022-06-28"
+          },
+          "body": {
+            "children": [
+              {
+                "object": "block",
+                "type": "paragraph",
+                "paragraph": {
+                  "rich_text": [
+                    {
+                      "type": "text",
+                      "text": {
+                        "content": "{{text}}"
+                      }
+                    }
+                  ]
+                }
+              }
+            ]
+          },
+          "paramMapping": {
+            "blockId": {
+              "required": true,
+              "encode": "uri"
+            },
+            "text": {
+              "required": true
+            }
+          },
+          "responseShape": {
+            "collectionPath": "results",
+            "collectionAs": "blocks",
+            "scalar": {
+              "count": "@count",
+              "blockId": "{{blockId}}"
+            }
+          }
+        }
+      }
+    ],
+    "provides": [
+      "fetch_record",
+      "list_records",
+      "manage_file",
+      "search_external"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/omniroute.capability.json

@@ -0,0 +1,137 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "omniroute",
+    "name": "OmniRoute — Sovereign Inference Gateway",
+    "description": "Connects a self-hosted OmniRoute gateway so agents can see its model catalog, routing decisions, per-provider health, cost and usage. Changing routing or flushing caches needs your approval. Needs a running OmniRoute instance (eve add omniroute) and an inference key from its dashboard.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "omniroute",
+    "name": "OmniRoute — Sovereign Inference Gateway",
+    "description": "Connects a self-hosted OmniRoute gateway (many upstream LLM providers behind one OpenAI-compatible /v1 endpoint, with its own dashboard) to this pod as a governed MCP server. Agents get live introspection — the model catalog, routing strategy, per-provider health, cost and usage — as INLINE read tools. Anything that CHANGES the gateway is a WRITE and goes through review. PRECONDITION: a running OmniRoute instance (`eve add omniroute`) and an inference key from its dashboard API Keys page.",
+    "params": [
+      {
+        "name": "baseUrl",
+        "label": "Gateway URL",
+        "type": "text",
+        "required": true,
+        "description": "Base URL of the OmniRoute gateway WITHOUT a trailing path, reachable from the intelligence service — e.g. https://omniroute.example.com. The MCP endpoint is <baseUrl>/api/mcp (note the /api prefix: /mcp does not exist)."
+      },
+      {
+        "name": "apiKey",
+        "label": "Inference API key",
+        "type": "text",
+        "required": true,
+        "description": "An inference key (sk-…) from OmniRoute's dashboard → API Keys. Stored server-encrypted as a pod-wide shared key; used only as the MCP transport's Authorization header, never shown to agents. A plain inference key gets 403 on OmniRoute's management routes, so do not expect the write tools below to work unless the key carries manage/admin scope."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "inferenceKey",
+        "name": "OmniRoute inference key",
+        "value": "{{apiKey}}",
+        "type": "api_key",
+        "podWide": true,
+        "description": "Service credential for the OmniRoute gateway's /api/mcp endpoint."
+      }
+    ],
+    "mcpServers": [
+      {
+        "slug": "omniroute",
+        "name": "OmniRoute",
+        "description": "Sovereign inference gateway introspection: model catalog, routing, provider health, cost and usage.",
+        "transport": "http",
+        "url": "{{baseUrl}}/api/mcp",
+        "enabled": true,
+        "auth": {
+          "credentialRef": "inferenceKey",
+          "header": "Authorization",
+          "prefix": "Bearer "
+        },
+        "toolPolicy": {
+          "default": "governed",
+          "inline": [
+            "omniroute_get_health",
+            "omniroute_list_models_catalog",
+            "omniroute_best_combo_for_task",
+            "omniroute_explain_route",
+            "omniroute_simulate_route",
+            "omniroute_get_provider_metrics",
+            "omniroute_get_combo_metrics",
+            "omniroute_cost_report",
+            "omniroute_cache_stats",
+            "omniroute_compression_status",
+            "omniroute_list_combos",
+            "omniroute_check_quota",
+            "omniroute_db_health_check"
+          ]
+        },
+        "metadata": {
+          "provider": "omniroute",
+          "docs": "https://hub.docker.com/r/diegosouzapw/omniroute",
+          "note": "Allowlist of READS, default governed: a write tool added upstream is gated automatically rather than silently inline. Tool names are the real ones exposed by the gateway's MCP server, verified against the running image — this gateway uses an `omniroute_` prefix, unlike most MCP servers."
+        }
+      }
+    ],
+    "tools": [
+      {
+        "name": "omniroute_mcp",
+        "kind": "mcp",
+        "description": "Governed gateway to the OmniRoute MCP server. The pod routes an agent's call to a non-inline tool (set_routing_strategy, cache_flush, switch_combo) through this row, where the capability gate turns it into a proposal. Path = MCP tool name; body = tool arguments.",
+        "credentialRef": "mcp://omniroute",
+        "executor": "is-agent",
+        "config": {
+          "serverSlug": "omniroute"
+        },
+        "metadata": {
+          "provider": "omniroute",
+          "mcpTools": [
+            "omniroute_get_health",
+            "omniroute_list_models_catalog",
+            "omniroute_best_combo_for_task",
+            "omniroute_explain_route",
+            "omniroute_simulate_route",
+            "omniroute_get_provider_metrics",
+            "omniroute_get_combo_metrics",
+            "omniroute_cost_report",
+            "omniroute_cache_stats",
+            "omniroute_compression_status",
+            "omniroute_list_combos",
+            "omniroute_check_quota",
+            "omniroute_db_health_check",
+            "omniroute_set_routing_strategy",
+            "omniroute_cache_flush",
+            "omniroute_switch_combo"
+          ],
+          "governedTools": [
+            "omniroute_set_routing_strategy",
+            "omniroute_cache_flush",
+            "omniroute_switch_combo",
+            "omniroute_set_budget_guard",
+            "omniroute_set_compression_engine",
+            "omniroute_set_resilience_profile",
+            "omniroute_create_combo",
+            "omniroute_sync_pricing"
+          ]
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "omniroute-gateway-advisor",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "When and how to use the OmniRoute gateway's MCP tools. Load when a model/provider choice depends on what the gateway can serve, a route behaves unexpectedly, or the user asks about inference cost or routing.",
+        "code": "# OmniRoute gateway\n\nOmniRoute fronts many upstream LLM providers behind one OpenAI-compatible `/v1` endpoint and exposes an MCP server for introspection and control. On this pod it is registered as a HIGH-PRIORITY provider (priority 1) because it is the operator's own gateway; FreeLLMAPI sits at 90 as a free last-resort lane.\n\n## Read tools (run immediately)\n\n| Tool | Use |\n|---|---|\n| `omniroute_get_health` | Is the gateway itself up and serving |\n| `omniroute_list_models_catalog` | Which models the gateway can serve, with context windows |\n| `omniroute_best_combo_for_task` | Which upstream combo suits a described task |\n| `omniroute_explain_route` | Why a request would route where it does |\n| `omniroute_simulate_route` | Dry-run a route decision without spending tokens |\n| `omniroute_get_provider_metrics` | Per-upstream health, cooldowns, error rates |\n| `omniroute_get_combo_metrics` | Per-combo latency and success |\n| `omniroute_cost_report` | What inference is costing, by model and route |\n| `omniroute_cache_stats` / `omniroute_compression_status` | Token savings |\n| `omniroute_check_quota` | Remaining quota on a provider |\n\n## Write tools (need the user's approval)\n\n`omniroute_set_routing_strategy`, `omniroute_switch_combo`, `omniroute_create_combo`, `omniroute_cache_flush`, `omniroute_set_budget_guard`, `omniroute_set_compression_engine`, `omniroute_set_resilience_profile`, `omniroute_sync_pricing`. Calling one files a proposal; it changes nothing until approved. Say what you proposed and why; do not retry it.\n\nNote: most write tools require the key to carry `manage` or `admin` scope. A plain inference key returns 403 on them — that is a credential problem, not a bug to route around.\n\n## Rules\n- Check `omniroute_get_provider_metrics` before blaming a model for a failure.\n- Prefer `omniroute_simulate_route` over a real request when the question is \"what would happen\".\n- Never claim a model is available without `omniroute_list_models_catalog` saying so.\n- Report numbers from `omniroute_cost_report` as measured, with the window."
+      }
+    ],
+    "provides": []
+  },
+  "dependencies": []
+}