@synap-core/workspace-templates 0.12.0 → 0.23.0

package/capabilities/backblaze-b2.capability.json

@@ -0,0 +1,205 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "backblaze-b2",
+    "name": "Backblaze B2 — Backup Storage",
+    "description": "Set up and check the B2 bucket that holds your pods' backups: list buckets and keys, check a bucket against the backup policy, see storage per pod and whether each pod's backups are recent. Creating or changing the bucket waits for your approval. Needs a B2 application key.",
+    "tags": [
+      "capability",
+      "backup",
+      "storage",
+      "backblaze",
+      "opt-in"
+    ],
+    "isPublic": true,
+    "syncByDefault": false
+  },
+  "spec": {
+    "key": "backblaze-b2",
+    "name": "Backblaze B2 — Backup Storage",
+    "description": "Set up and audit Backblaze B2 backup storage for Synap pods. Pod backups go to ONE versioned, private B2 bucket; each pod writes under pods/<podId>/ with its own key that cannot delete. READ verbs (run without approval): list buckets, read a bucket's settings against the backup policy, list keys, storage used per pods/<podId>/ prefix, and whether a pod's backups are present and recent (newest restic snapshot). WRITE verb (always proposal-gated): create or configure THE backup bucket — private, keep all versions, lifecycle rule {fileNamePrefix:\"pods/\", daysFromHidingToDeleting:30, daysFromUploadingToHiding:null}, Object Lock off. OUT OF SCOPE ON PURPOSE: deleting buckets, files or keys, and minting per-pod keys. Per-pod keys are minted ONLY by the control-plane backup vault (one key-minting door), so this capability never holds writeKeys or deleteKeys. Auth: signs in with b2_authorize_account (HTTP Basic keyID:applicationKey) and calls the account's own apiUrl with the returned token, cached up to 24h and refreshed on expiry. PRECONDITION: a B2 application key with exactly these capabilities: listBuckets, writeBuckets, readBucketRetentions, listFiles, listKeys — all buckets (no bucket or prefix restriction). Not needed: readBuckets (S3-API only), writeKeys (no verb mints keys). readBucketRetentions is what lets the Object Lock state be read.",
+    "params": [
+      {
+        "name": "b2Credential",
+        "label": "B2 application key (keyID:applicationKey)",
+        "type": "text",
+        "required": true,
+        "description": "Your B2 application key as keyID:applicationKey — the keyID, a colon, then the applicationKey (B2 shows the applicationKey only once, when the key is created). Capabilities: listBuckets, writeBuckets, readBucketRetentions, listFiles, listKeys. Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "b2CredentialSecret",
+        "name": "{{name}} B2 application key",
+        "value": "{{b2Credential}}",
+        "type": "api_key",
+        "description": "B2 application key for the b2_api connector, stored as keyID:applicationKey. Used only to sign in (b2_authorize_account); the token it returns is held in pod memory, never stored."
+      }
+    ],
+    "tools": [
+      {
+        "name": "b2_api",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the Backblaze B2 native API v4. Signs in with b2_authorize_account (HTTP Basic keyID:applicationKey), then sends each call to the account's apiUrl with the returned authorizationToken; re-signs in once on expired_auth_token / bad_auth_token. accountId comes from the sign-in, filled into any request body that declares it. Its credentialRef is remapped to the runtime vault://<id> at apply time.",
+        "credentialRef": "b2CredentialSecret",
+        "executor": "is-agent",
+        "config": {
+          "auth": {
+            "type": "session",
+            "signIn": {
+              "url": "https://api.backblazeb2.com/b2api/v4/b2_authorize_account",
+              "method": "GET",
+              "credential": "basic"
+            },
+            "token": {
+              "path": "authorizationToken",
+              "header": "Authorization",
+              "prefix": "",
+              "ttlSeconds": 86400
+            },
+            "baseUrlFrom": "apiInfo.storageApi.apiUrl",
+            "bodyFrom": {
+              "accountId": "accountId"
+            },
+            "reauthOn": {
+              "status": 401,
+              "codePath": "code",
+              "codes": [
+                "expired_auth_token",
+                "bad_auth_token"
+              ]
+            }
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "b2_list_buckets",
+        "intent": "list_records",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Lists the B2 account's buckets (name, id, type, lifecycle rules, revision). Read-only, no side effects. Args: { bucketName?: string (only that bucket) }.",
+        "requires": [
+          "b2_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "bucketName": "string?"
+        },
+        "metadata": {
+          "readOnly": true
+        },
+        "code": "// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. Calling the b2_api tool (a POST to /b2api/v4/<op>)\n// signs in to B2 for you (auth.type \"session\": b2_authorize_account, token\n// cached), calls the per-account apiUrl, and fills `accountId` into a body that\n// declares it (accountId: null) — B2 rejects it on ops that do not take it.\n// B2 native API v4 — every operation is a POST with a JSON body.\nconst b2 = async (op, body) => {\n  const res = await callProvider('b2_api', 'POST', `/b2api/v4/${op}`, body || {});\n  if (res && res.proposed === true) return { proposed: true, proposalId: res.proposalId || null };\n  return (res && res.body) || {};\n};\nconst body = { accountId: null };\nconst name = String(args?.bucketName ?? '').trim();\nif (name) body.bucketName = name;\nconst res = await b2('b2_list_buckets', body);\nconst buckets = (Array.isArray(res.buckets) ? res.buckets : []).map((b) => ({\n  bucketName: b.bucketName,\n  bucketId: b.bucketId,\n  bucketType: b.bucketType,\n  lifecycleRules: Array.isArray(b.lifecycleRules) ? b.lifecycleRules : [],\n  revision: b.revision ?? null,\n}));\nreturn { count: buckets.length, buckets };\n"
+      },
+      {
+        "name": "b2_get_bucket_settings",
+        "intent": "fetch_record",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Reads one bucket's settings — type (private/public), versioning (B2 keeps every version; lifecycle rules decide purging), lifecycle rules, Object Lock, default encryption — and checks them against the backup policy: private, ONE lifecycle rule {fileNamePrefix:\"pods/\", daysFromHidingToDeleting:30, daysFromUploadingToHiding:null}, Object Lock off. Read-only. Object Lock reads as \"unreadable\" when the key lacks readBucketRetentions. Args: { bucketName: string }.",
+        "requires": [
+          "b2_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "bucketName": "string"
+        },
+        "metadata": {
+          "readOnly": true
+        },
+        "code": "// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. Calling the b2_api tool (a POST to /b2api/v4/<op>)\n// signs in to B2 for you (auth.type \"session\": b2_authorize_account, token\n// cached), calls the per-account apiUrl, and fills `accountId` into a body that\n// declares it (accountId: null) — B2 rejects it on ops that do not take it.\n// B2 native API v4 — every operation is a POST with a JSON body.\nconst b2 = async (op, body) => {\n  const res = await callProvider('b2_api', 'POST', `/b2api/v4/${op}`, body || {});\n  if (res && res.proposed === true) return { proposed: true, proposalId: res.proposalId || null };\n  return (res && res.body) || {};\n};\nconst BACKUP_RULE = { fileNamePrefix: 'pods/', daysFromHidingToDeleting: 30, daysFromUploadingToHiding: null };\nconst isBackupRule = (r) => !!r && r.fileNamePrefix === 'pods/' && r.daysFromHidingToDeleting === 30 && (r.daysFromUploadingToHiding === null || r.daysFromUploadingToHiding === undefined);\nconst objectLockOf = (b) => {\n  const fl = b && b.fileLockConfiguration;\n  if (!fl || fl.isClientAuthorizedToRead !== true) return 'unreadable';\n  return fl.value && fl.value.isFileLockEnabled === true ? 'on' : 'off';\n};\nconst policyOf = (b) => {\n  const rules = Array.isArray(b.lifecycleRules) ? b.lifecycleRules : [];\n  const podRules = rules.filter((r) => r && r.fileNamePrefix === 'pods/');\n  const objectLock = objectLockOf(b);\n  const check = {\n    private: b.bucketType === 'allPrivate',\n    lifecycleRule: podRules.length === 1 && isBackupRule(podRules[0]),\n    objectLock,\n  };\n  return { ...check, compliant: check.private && check.lifecycleRule && objectLock === 'off' };\n};\nconst bucketName = String(args?.bucketName ?? '').trim();\nif (!/^[A-Za-z0-9][A-Za-z0-9.-]{4,61}[A-Za-z0-9]$/.test(bucketName)) {\n  throw new Error('bucketName is required: 6-63 letters, digits, hyphens or periods');\n}\nconst listed = await b2('b2_list_buckets', { accountId: null, bucketName });\nconst bucket = (Array.isArray(listed.buckets) ? listed.buckets : []).find((b) => b && b.bucketName === bucketName) || null;\nif (!bucket) return { found: false, bucketName };\nreturn {\n  found: true,\n  bucketName,\n  bucketId: bucket.bucketId,\n  bucketType: bucket.bucketType,\n  // B2 keeps every version of a file by default; there is no versioning switch.\n  // Old versions are only removed by a lifecycle rule.\n  versioning: 'keep-all-versions (B2 default; lifecycle rules decide purging)',\n  lifecycleRules: Array.isArray(bucket.lifecycleRules) ? bucket.lifecycleRules : [],\n  objectLock: objectLockOf(bucket),\n  fileLockConfiguration: bucket.fileLockConfiguration ?? null,\n  defaultServerSideEncryption: bucket.defaultServerSideEncryption ?? null,\n  options: bucket.options ?? [],\n  revision: bucket.revision ?? null,\n  backupPolicy: { expected: { bucketType: 'allPrivate', lifecycleRule: BACKUP_RULE, objectLock: 'off' }, ...policyOf(bucket) },\n};\n"
+      },
+      {
+        "name": "b2_list_keys",
+        "intent": "list_records",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Lists the account's application keys — id, name, capabilities, bucket and namePrefix restrictions, expiry. Never returns a key's secret (B2 does not). Use it to audit that each pod key is scoped to pods/<podId>/ and has no deleteFiles. Read-only. Args: { maxKeyCount?: number (default 100, max 1000), startApplicationKeyId?: string (next page) }.",
+        "requires": [
+          "b2_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "maxKeyCount": "number?",
+          "startApplicationKeyId": "string?"
+        },
+        "metadata": {
+          "readOnly": true
+        },
+        "code": "// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. Calling the b2_api tool (a POST to /b2api/v4/<op>)\n// signs in to B2 for you (auth.type \"session\": b2_authorize_account, token\n// cached), calls the per-account apiUrl, and fills `accountId` into a body that\n// declares it (accountId: null) — B2 rejects it on ops that do not take it.\n// B2 native API v4 — every operation is a POST with a JSON body.\nconst b2 = async (op, body) => {\n  const res = await callProvider('b2_api', 'POST', `/b2api/v4/${op}`, body || {});\n  if (res && res.proposed === true) return { proposed: true, proposalId: res.proposalId || null };\n  return (res && res.body) || {};\n};\nconst n = Number(args?.maxKeyCount);\nconst maxKeyCount = Number.isFinite(n) ? Math.max(1, Math.min(1000, Math.trunc(n))) : 100;\nconst body = { accountId: null, maxKeyCount };\nconst start = String(args?.startApplicationKeyId ?? '').trim();\nif (start) body.startApplicationKeyId = start;\nconst res = await b2('b2_list_keys', body);\n// b2_list_keys never returns a key's secret — only its id and restrictions.\nconst keys = (Array.isArray(res.keys) ? res.keys : []).map((k) => ({\n  applicationKeyId: k.applicationKeyId,\n  keyName: k.keyName,\n  capabilities: k.capabilities ?? [],\n  bucketIds: k.bucketIds ?? (k.bucketId ? [k.bucketId] : null),\n  namePrefix: k.namePrefix ?? null,\n  expirationTimestamp: k.expirationTimestamp ?? null,\n}));\nreturn { count: keys.length, keys, nextApplicationKeyId: res.nextApplicationKeyId ?? null };\n"
+      },
+      {
+        "name": "b2_storage_by_pod",
+        "intent": "fetch_record",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Storage used under pods/<podId>/ in a bucket: total bytes of every stored version, version count and hide markers. Without podId, sums every pods/<id>/ folder. Read-only, but it pages through file versions (B2 Class C calls, 1000 versions per page; maxPages caps the scan and `truncated` says when it stopped early). Args: { bucketName: string, podId?: string, maxPages?: number (default 20, max 100) }.",
+        "requires": [
+          "b2_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 120,
+        "parameters": {
+          "bucketName": "string",
+          "podId": "string?",
+          "maxPages": "number?"
+        },
+        "metadata": {
+          "readOnly": true
+        },
+        "code": "// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. Calling the b2_api tool (a POST to /b2api/v4/<op>)\n// signs in to B2 for you (auth.type \"session\": b2_authorize_account, token\n// cached), calls the per-account apiUrl, and fills `accountId` into a body that\n// declares it (accountId: null) — B2 rejects it on ops that do not take it.\n// B2 native API v4 — every operation is a POST with a JSON body.\nconst b2 = async (op, body) => {\n  const res = await callProvider('b2_api', 'POST', `/b2api/v4/${op}`, body || {});\n  if (res && res.proposed === true) return { proposed: true, proposalId: res.proposalId || null };\n  return (res && res.body) || {};\n};\nconst podIdOf = (v) => {\n  const id = String(v ?? '').trim();\n  if (!/^[A-Za-z0-9-]{1,64}$/.test(id)) throw new Error('podId must be letters, digits or hyphens (a pod id), never a path');\n  return id;\n};\nconst bucketName = String(args?.bucketName ?? '').trim();\nif (!/^[A-Za-z0-9][A-Za-z0-9.-]{4,61}[A-Za-z0-9]$/.test(bucketName)) {\n  throw new Error('bucketName is required: 6-63 letters, digits, hyphens or periods');\n}\nconst listed = await b2('b2_list_buckets', { accountId: null, bucketName });\nconst bucket = (Array.isArray(listed.buckets) ? listed.buckets : []).find((b) => b && b.bucketName === bucketName) || null;\nif (!bucket) throw new Error(`bucket \"${bucketName}\" not found`);\nconst m = Number(args?.maxPages);\nlet budget = Number.isFinite(m) ? Math.max(1, Math.min(100, Math.trunc(m))) : 20;\nconst sumPrefix = async (prefix) => {\n  let bytes = 0, versions = 0, hidden = 0, startFileName = null, startFileId = null, truncated = false;\n  for (;;) {\n    if (budget <= 0) { truncated = true; break; }\n    budget -= 1;\n    const body = { bucketId: bucket.bucketId, prefix, maxFileCount: 1000 };\n    if (startFileName) { body.startFileName = startFileName; if (startFileId) body.startFileId = startFileId; }\n    const page = await b2('b2_list_file_versions', body);\n    for (const f of (Array.isArray(page.files) ? page.files : [])) {\n      if (f.action === 'upload') { bytes += Number(f.contentLength) || 0; versions += 1; }\n      else if (f.action === 'hide') hidden += 1;\n    }\n    if (!page.nextFileName) break;\n    startFileName = page.nextFileName;\n    startFileId = page.nextFileId || null;\n  }\n  return { prefix, bytes, versions, hiddenMarkers: hidden, truncated };\n};\nlet podIds;\nif (args?.podId) {\n  podIds = [podIdOf(args.podId)];\n} else {\n  podIds = [];\n  let startFileName = null;\n  for (;;) {\n    budget -= 1;\n    const body = { bucketId: bucket.bucketId, prefix: 'pods/', delimiter: '/', maxFileCount: 1000 };\n    if (startFileName) body.startFileName = startFileName;\n    const page = await b2('b2_list_file_names', body);\n    for (const f of (Array.isArray(page.files) ? page.files : [])) {\n      const mm = /^pods\\/([^/]+)\\/$/.exec(String(f.fileName || ''));\n      if (f.action === 'folder' && mm) podIds.push(mm[1]);\n    }\n    if (!page.nextFileName || budget <= 0) break;\n    startFileName = page.nextFileName;\n  }\n}\nconst pods = [];\nfor (const id of podIds) pods.push({ podId: id, ...(await sumPrefix(`pods/${id}/`)) });\nconst totalBytes = pods.reduce((a, p) => a + p.bytes, 0);\nreturn { bucketName, pods, totalBytes, truncated: pods.some((p) => p.truncated) };\n"
+      },
+      {
+        "name": "b2_backup_freshness",
+        "intent": "fetch_record",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Are this pod's backups present and recent? Lists the restic snapshot files under pods/<podId>/snapshots/ and reports the newest upload time, its age in hours, and recent = age <= maxAgeHours. Read-only. Args: { bucketName: string, podId: string, maxAgeHours?: number (default 26) }.",
+        "requires": [
+          "b2_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "bucketName": "string",
+          "podId": "string",
+          "maxAgeHours": "number?"
+        },
+        "metadata": {
+          "readOnly": true
+        },
+        "code": "// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. Calling the b2_api tool (a POST to /b2api/v4/<op>)\n// signs in to B2 for you (auth.type \"session\": b2_authorize_account, token\n// cached), calls the per-account apiUrl, and fills `accountId` into a body that\n// declares it (accountId: null) — B2 rejects it on ops that do not take it.\n// B2 native API v4 — every operation is a POST with a JSON body.\nconst b2 = async (op, body) => {\n  const res = await callProvider('b2_api', 'POST', `/b2api/v4/${op}`, body || {});\n  if (res && res.proposed === true) return { proposed: true, proposalId: res.proposalId || null };\n  return (res && res.body) || {};\n};\nconst podIdOf = (v) => {\n  const id = String(v ?? '').trim();\n  if (!/^[A-Za-z0-9-]{1,64}$/.test(id)) throw new Error('podId must be letters, digits or hyphens (a pod id), never a path');\n  return id;\n};\nconst bucketName = String(args?.bucketName ?? '').trim();\nif (!/^[A-Za-z0-9][A-Za-z0-9.-]{4,61}[A-Za-z0-9]$/.test(bucketName)) {\n  throw new Error('bucketName is required: 6-63 letters, digits, hyphens or periods');\n}\nconst listed = await b2('b2_list_buckets', { accountId: null, bucketName });\nconst bucket = (Array.isArray(listed.buckets) ? listed.buckets : []).find((b) => b && b.bucketName === bucketName) || null;\nif (!bucket) throw new Error(`bucket \"${bucketName}\" not found`);\nconst podId = podIdOf(args?.podId);\nconst h = Number(args?.maxAgeHours);\nconst maxAgeHours = Number.isFinite(h) && h > 0 ? h : 26;\n// restic writes one file per snapshot under <repo>/snapshots/; the pod's repo is\n// b2:<bucket>:pods/<podId> (CP backup vault), so this lists ONLY snapshot\n// files — never the pack data. b2_list_file_names returns the latest visible\n// version of each name (hidden files are excluded).\nconst prefix = `pods/${podId}/snapshots/`;\nlet newest = null, count = 0, startFileName = null, pages = 0, truncated = false;\nfor (;;) {\n  if (pages >= 10) { truncated = true; break; }\n  pages += 1;\n  const body = { bucketId: bucket.bucketId, prefix, maxFileCount: 1000 };\n  if (startFileName) body.startFileName = startFileName;\n  const page = await b2('b2_list_file_names', body);\n  for (const f of (Array.isArray(page.files) ? page.files : [])) {\n    if (f.action !== 'upload') continue;\n    count += 1;\n    if (!newest || Number(f.uploadTimestamp) > Number(newest.uploadTimestamp)) newest = f;\n  }\n  if (!page.nextFileName) break;\n  startFileName = page.nextFileName;\n}\nconst newestAt = newest ? new Date(Number(newest.uploadTimestamp)).toISOString() : null;\nconst ageHours = newest ? Math.round(((Date.now() - Number(newest.uploadTimestamp)) / 3600000) * 10) / 10 : null;\nreturn {\n  podId, bucketName, prefix,\n  present: count > 0,\n  snapshotCount: count,\n  newestSnapshotAt: newestAt,\n  ageHours,\n  maxAgeHours,\n  recent: ageHours !== null && ageHours <= maxAgeHours,\n  truncated,\n};\n"
+      },
+      {
+        "name": "b2_ensure_backup_bucket",
+        "intent": "manage_file",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Creates THE backup bucket, or brings an existing one to the backup policy: private (allPrivate), B2's default keep-all-versions, ONE lifecycle rule {fileNamePrefix:\"pods/\", daysFromHidingToDeleting:30, daysFromUploadingToHiding:null} (other rules are kept), Object Lock off. Changes the B2 account, so it is NOT read-only: an agent's run waits for your approval. Refuses a bucket that already has Object Lock on (B2 cannot turn it off). Never deletes anything. Args: { bucketName: string }.",
+        "requires": [
+          "b2_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "bucketName": "string"
+        },
+        "metadata": {
+          "verbType": "write"
+        },
+        "code": "// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. Calling the b2_api tool (a POST to /b2api/v4/<op>)\n// signs in to B2 for you (auth.type \"session\": b2_authorize_account, token\n// cached), calls the per-account apiUrl, and fills `accountId` into a body that\n// declares it (accountId: null) — B2 rejects it on ops that do not take it.\n// B2 native API v4 — every operation is a POST with a JSON body.\nconst b2 = async (op, body) => {\n  const res = await callProvider('b2_api', 'POST', `/b2api/v4/${op}`, body || {});\n  if (res && res.proposed === true) return { proposed: true, proposalId: res.proposalId || null };\n  return (res && res.body) || {};\n};\nconst BACKUP_RULE = { fileNamePrefix: 'pods/', daysFromHidingToDeleting: 30, daysFromUploadingToHiding: null };\nconst isBackupRule = (r) => !!r && r.fileNamePrefix === 'pods/' && r.daysFromHidingToDeleting === 30 && (r.daysFromUploadingToHiding === null || r.daysFromUploadingToHiding === undefined);\nconst objectLockOf = (b) => {\n  const fl = b && b.fileLockConfiguration;\n  if (!fl || fl.isClientAuthorizedToRead !== true) return 'unreadable';\n  return fl.value && fl.value.isFileLockEnabled === true ? 'on' : 'off';\n};\nconst policyOf = (b) => {\n  const rules = Array.isArray(b.lifecycleRules) ? b.lifecycleRules : [];\n  const podRules = rules.filter((r) => r && r.fileNamePrefix === 'pods/');\n  const objectLock = objectLockOf(b);\n  const check = {\n    private: b.bucketType === 'allPrivate',\n    lifecycleRule: podRules.length === 1 && isBackupRule(podRules[0]),\n    objectLock,\n  };\n  return { ...check, compliant: check.private && check.lifecycleRule && objectLock === 'off' };\n};\nconst bucketName = String(args?.bucketName ?? '').trim();\nif (!/^[A-Za-z0-9][A-Za-z0-9.-]{4,61}[A-Za-z0-9]$/.test(bucketName)) {\n  throw new Error('bucketName is required: 6-63 letters, digits, hyphens or periods');\n}\nconst listed = await b2('b2_list_buckets', { accountId: null, bucketName });\nconst bucket = (Array.isArray(listed.buckets) ? listed.buckets : []).find((b) => b && b.bucketName === bucketName) || null;\nif (!bucket) {\n  const created = await b2('b2_create_bucket', {\n    accountId: null,\n    bucketName,\n    bucketType: 'allPrivate',\n    lifecycleRules: [BACKUP_RULE],\n    fileLockEnabled: false,\n  });\n  if (created.proposed) return { proposed: true, proposalId: created.proposalId, bucketName };\n  return { action: 'created', bucketName, bucketId: created.bucketId ?? null, backupPolicy: policyOf(created) };\n}\nif (objectLockOf(bucket) === 'on') {\n  throw new Error(`bucket \"${bucketName}\" has Object Lock enabled, and B2 cannot turn it off. Restic cannot remove its own lock files under Object Lock: use a new bucket without it.`);\n}\nconst before = policyOf(bucket);\nif (before.private && before.lifecycleRule) {\n  return { action: 'unchanged', bucketName, bucketId: bucket.bucketId, backupPolicy: before };\n}\n// Keep every rule that is not about pods/; replace the pods/ rule(s) with THE rule.\nconst others = (Array.isArray(bucket.lifecycleRules) ? bucket.lifecycleRules : []).filter((r) => !r || r.fileNamePrefix !== 'pods/');\nconst body = { accountId: null, bucketId: bucket.bucketId, bucketType: 'allPrivate', lifecycleRules: [...others, BACKUP_RULE] };\nif (typeof bucket.revision === 'number') body.ifRevisionIs = bucket.revision;\nconst updated = await b2('b2_update_bucket', body);\nif (updated.proposed) return { proposed: true, proposalId: updated.proposalId, bucketName };\nreturn { action: 'updated', bucketName, bucketId: bucket.bucketId, before, backupPolicy: policyOf(updated), keptRules: others };\n"
+      }
+    ],
+    "provides": [
+      "list_records",
+      "fetch_record",
+      "manage_file"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/cal-com.capability.json

@@ -0,0 +1,266 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "cal-com",
+    "name": "Cal.com Scheduling",
+    "description": "Check availability, list event types and bookings, and create or cancel Cal.com bookings from Synap. New bookings and cancellations follow your approval rules. Needs a Cal.com API key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "cal-com",
+    "name": "Cal.com Scheduling",
+    "description": "Scheduling via the Cal.com API v2 (base https://api.cal.com/v2) using API-key auth. Stores the Cal.com API key in the vault, registers one HTTP API tool that authenticates with `Authorization: Bearer <cal_live_key>`, and seeds read + write scheduling skills. Reads (cal_list_bookings, cal_get_slots, cal_list_event_types, cal_me) are `declarative` skills that return data inline; writes (cal_create_booking, cal_cancel_booking) are proposal-gated `code` skills that route through the capability-execution gate. GOTCHA: every Cal.com v2 endpoint requires a per-endpoint `cal-api-version` header (e.g. /bookings + /event-types + /me => 2024-08-13, /slots => 2024-09-04); provider skills set it via providerSpec.headers and code skills pass it via callProvider's opts.headers. Rides on the shipped `vault://` executor: 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. PRECONDITION: a Cal.com account with an API key (Settings -> Developer -> API Keys, a `cal_live_...` token). Pass it as `calApiKey`.",
+    "params": [
+      {
+        "name": "calApiKey",
+        "label": "Cal.com API key",
+        "type": "text",
+        "required": true,
+        "description": "The Cal.com API key (Settings -> Developer -> API Keys, a `cal_live_...` token). Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "calApiKeySecret",
+        "name": "{{name}} Cal.com API key",
+        "value": "{{calApiKey}}",
+        "type": "api_key",
+        "description": "Cal.com API v2 key for the cal_com connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "cal_com",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the Cal.com API v2. 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. NOTE: each v2 endpoint also needs a per-endpoint `cal-api-version` header, supplied per-skill (providerSpec.headers for reads, callProvider opts.headers for writes).",
+        "credentialRef": "calApiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.cal.com/v2",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "cal_list_bookings",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists upcoming Cal.com bookings (uid, title, start, end, status, location, meeting/video URL, attendees). No args.",
+        "requires": [
+          "cal_com"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {},
+        "providerSpec": {
+          "tool": "cal_com",
+          "method": "GET",
+          "pathTemplate": "/bookings",
+          "headers": {
+            "cal-api-version": "2024-08-13"
+          },
+          "query": {
+            "status": "upcoming"
+          },
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "bookings",
+            "item": {
+              "id": "id",
+              "uid": "uid",
+              "title": "title",
+              "start": "start",
+              "end": "end",
+              "status": "status",
+              "location": "location",
+              "meetingUrl": "meetingUrl",
+              "attendees": "attendees"
+            },
+            "scalar": {
+              "count": "@count"
+            }
+          }
+        }
+      },
+      {
+        "name": "cal_get_booking",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Fetches full detail for ONE Cal.com booking by uid — attendees, start/end, status, location, meeting/video URL, and the booking-form responses. Args: { uid: string }.",
+        "requires": [
+          "cal_com"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "uid": "string"
+        },
+        "providerSpec": {
+          "tool": "cal_com",
+          "method": "GET",
+          "pathTemplate": "/bookings/{{uid}}",
+          "headers": {
+            "cal-api-version": "2024-08-13"
+          },
+          "paramMapping": {
+            "uid": {
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "id": "data.id",
+              "uid": "data.uid",
+              "title": "data.title",
+              "start": "data.start",
+              "end": "data.end",
+              "status": "data.status",
+              "location": "data.location",
+              "meetingUrl": "data.meetingUrl",
+              "attendees": "data.attendees",
+              "responses": "data.responses"
+            }
+          }
+        }
+      },
+      {
+        "name": "cal_get_slots",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Returns available booking slots for an event type within a date range. Args: { eventTypeId: number|string, start: string (YYYY-MM-DD or RFC3339), end: string, timeZone?: string (default 'UTC') }.",
+        "requires": [
+          "cal_com"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "eventTypeId": "string",
+          "start": "string",
+          "end": "string",
+          "timeZone": "string"
+        },
+        "providerSpec": {
+          "tool": "cal_com",
+          "method": "GET",
+          "pathTemplate": "/slots",
+          "headers": {
+            "cal-api-version": "2024-09-04"
+          },
+          "query": {
+            "eventTypeId": "{{eventTypeId}}",
+            "start": "{{start}}",
+            "end": "{{end}}",
+            "timeZone": "{{timeZone}}"
+          },
+          "paramMapping": {
+            "timeZone": {
+              "default": "UTC"
+            }
+          }
+        }
+      },
+      {
+        "name": "cal_list_event_types",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the connected user's Cal.com event types. No args.",
+        "requires": [
+          "cal_com"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {},
+        "providerSpec": {
+          "tool": "cal_com",
+          "method": "GET",
+          "pathTemplate": "/event-types",
+          "headers": {
+            "cal-api-version": "2024-08-13"
+          },
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "eventTypes"
+          }
+        }
+      },
+      {
+        "name": "cal_me",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Returns the authenticated Cal.com user profile. No args.",
+        "requires": [
+          "cal_com"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {},
+        "providerSpec": {
+          "tool": "cal_com",
+          "method": "GET",
+          "pathTemplate": "/me",
+          "headers": {
+            "cal-api-version": "2024-08-13"
+          }
+        }
+      },
+      {
+        "name": "cal_create_booking",
+        "intent": "schedule_event",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Creates a Cal.com booking and notes it as an event entity (proposal-gated). Args: { start: string (RFC3339), eventTypeId: number|string, name: string, email: string, timeZone?: string (default 'UTC') }.",
+        "requires": [
+          "cal_com"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "start": "string",
+          "eventTypeId": "string",
+          "name": "string",
+          "email": "string",
+          "timeZone": "string?"
+        },
+        "code": "// Create a Cal.com booking (side-effecting write). Executor wraps this body as\n// (async (args, context) => { <code> }); use args directly and `return`.\n// callProvider(tool, method, path, body?, opts?) resolves the cal_com tool by\n// NAME, injects the vaulted key as Authorization: Bearer <key>, and uses the\n// tool's config.baseUrl = https://api.cal.com/v2. Cal.com v2 requires a\n// per-endpoint version header — passed via opts.headers ('cal-api-version').\nconst start = String(args?.start ?? '').trim();\nif (!start) throw new Error('cal_create_booking: start is required (RFC3339, e.g. 2026-07-01T15:00:00Z)');\nconst eventTypeRaw = args?.eventTypeId;\nif (eventTypeRaw === undefined || eventTypeRaw === null || String(eventTypeRaw).trim() === '') throw new Error('cal_create_booking: eventTypeId is required');\nconst eventTypeId = Number(eventTypeRaw);\nif (!Number.isFinite(eventTypeId)) throw new Error('cal_create_booking: eventTypeId must be numeric');\nconst name = String(args?.name ?? '').trim();\nif (!name) throw new Error('cal_create_booking: name (attendee) is required');\nconst email = String(args?.email ?? '').trim();\nif (!email) throw new Error('cal_create_booking: email (attendee) is required');\nconst timeZone = String(args?.timeZone ?? 'UTC').trim() || 'UTC';\n\nconst payload = { start, eventTypeId, attendee: { name, timeZone, email } };\nconst res = await callProvider('cal_com', 'POST', '/bookings', payload, { headers: { 'cal-api-version': '2024-08-13' } });\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 an event (no double-proposal).\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, start, email };\n}\nconst ok = typeof res?.status === 'number' && res.status >= 200 && res.status < 300;\nconst body = res?.body ?? res;\nconst data = body?.data ?? body ?? {};\nconst uid = data?.uid ?? null;\nconst title = data?.title ?? ('Booking with ' + name);\nconst startDate = data?.start ?? start;\nconst endDate = data?.end ?? null;\nconst calendarLink = data?.meetingUrl ?? data?.location ?? null;\n\n// Shape the event to match event-sync's normalizeEntity (startDate/endDate/\n// calendarLink), so the booking mirrors to Discord like any other event.\nawait propose.entity({\n  profileSlug: 'event',\n  title: title,\n  properties: { startDate, endDate, calendarLink, provenance: 'connector', provider: 'cal.com', calBookingUid: uid },\n  reasoning: 'Recorded the Cal.com booking for the activity timeline.'\n});\nreturn { success: ok, proposed: false, uid };"
+      },
+      {
+        "name": "cal_cancel_booking",
+        "intent": "schedule_event",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Cancels a Cal.com booking by uid and notes the cancellation (proposal-gated). Args: { uid: string, cancellationReason?: string }.",
+        "requires": [
+          "cal_com"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "uid": "string",
+          "cancellationReason": "string"
+        },
+        "code": "// Cancel a Cal.com booking (side-effecting write). callProvider resolves the\n// cal_com tool by NAME and injects the vaulted key; opts.headers carries the\n// required per-endpoint version header.\nconst uid = String(args?.uid ?? '').trim();\nif (!uid) throw new Error('cal_cancel_booking: uid is required');\nconst cancellationReason = String(args?.cancellationReason ?? '').trim();\n\nconst res = await callProvider('cal_com', 'POST', '/bookings/' + encodeURIComponent(uid) + '/cancel', { cancellationReason }, { headers: { 'cal-api-version': '2024-08-13' } });\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, uid };\n}\nconst ok = typeof res?.status === 'number' && res.status >= 200 && res.status < 300;\n\nawait propose.entity({\n  profileSlug: 'event',\n  title: 'Cal.com booking ' + (ok ? 'cancelled' : 'cancel attempted') + ': ' + uid,\n  properties: { action: 'cal_cancel_booking', calBookingUid: uid, cancellationReason, provenance: 'connector', provider: 'cal.com', success: ok },\n  reasoning: 'Recorded the Cal.com booking cancellation for the activity timeline.'\n});\nreturn { success: ok, proposed: false, uid };"
+      }
+    ],
+    "provides": [
+      "list_records",
+      "fetch_record",
+      "schedule_event"
+    ]
+  },
+  "dependencies": []
+}