@synap-core/workspace-templates 0.12.0 → 0.24.0

package/capabilities/proton.capability.json

@@ -0,0 +1,288 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "proton",
+    "name": "Proton Mail (self-hosted Bridge)",
+    "description": "Reads your full Proton Mail inbox through a Proton Bridge on your own server, so mail is decrypted locally. Includes a draft-reply playbook (you approve every send) and optional triage for unknown senders. Needs your Proton login.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "proton",
+    "name": "Proton Mail (self-hosted bridge)",
+    "description": "SOVEREIGN self-host path for Proton Mail: a locally-run Proton Bridge (headless, `synap proton-setup`-provisioned) decrypts Proton's end-to-end-encrypted mail and exposes it as plain IMAP/SMTP on localhost, which this connector polls. This is the alternative to the `mailgun` template's Proton-forward path (a Proton auto-forward rule to a Mailgun catch-all inbound address) — that path is simpler to provision but round-trips mail through Mailgun's servers and only forwards what the Proton account chooses to forward. This path keeps mail local (the bridge decrypts on the user's own host) and reads the full mailbox, at the cost of requiring the bridge process to stay running. MUTUAL EXCLUSIVITY: do NOT run both a Proton Bridge connector (this template) and a Proton-forward-to-Mailgun rule (the `mailgun` template's Proton coverage) for the SAME mailbox — the same message would land twice, once via each pipeline (double-ingest into the channel/message substrate). Pick exactly one path per Proton mailbox. SELF-SERVE CREDENTIAL MODEL: enter your normal proton.me sign-in email + password (and a 2FA/TOTP seed if you have one enabled) — the headless bridge auto-logs-in with these on boot, no manual bridge login required. This is your regular account login — it is NOT the Organization key/name/password found under Settings → Organization (that is Business-admin-only machinery for activating/recovering admin status and is never used to log a mail client in). If your account uses two-password mode (a separate mailbox password on top of the login password), also provide `protonMailboxPassword`. Accounts secured with a FIDO2/security-key as their only 2FA method cannot be headless-automated — switch that account to TOTP first, or do one interactive bridge login. If Proton throws a one-time human-verification challenge (more likely on datacenter/VPS IPs than a home connection), a URL appears in the bridge logs (`pm2 logs proton-bridge`); click it once in a browser and the bridge finishes logging in — this is a one-time step, not a recurring one. Pass the account credentials as `protonEmail` / `protonPassword` / `protonTotpSeed` / `protonMailboxPassword`.",
+    "metadata": {
+      "mode": "standing"
+    },
+    "params": [
+      {
+        "name": "protonEmail",
+        "label": "Proton account email",
+        "type": "text",
+        "required": true,
+        "description": "The Proton ACCOUNT email address (the one you sign in to proton.me with) — NOT a bridge-generated value. Used by the headless bridge to auto-log-in on boot."
+      },
+      {
+        "name": "protonPassword",
+        "label": "Proton account password",
+        "type": "password",
+        "required": true,
+        "description": "Your normal proton.me sign-in password — NOT the Bridge-generated IMAP/SMTP password, and NOT the Organization key/password (Settings → Organization, Business-admin-only, never used to log a mail client in). Two-password-mode accounts: this is the LOGIN password; provide the separate mailbox password via `protonMailboxPassword`. Stored server-encrypted in the vault; never persisted in the template. Used by the headless bridge to auto-log-in on boot."
+      },
+      {
+        "name": "protonTotpSeed",
+        "label": "Proton 2FA/TOTP seed (optional)",
+        "type": "password",
+        "required": false,
+        "description": "Base32 TOTP/2FA secret seed from your Proton account's two-factor authenticator setup (Settings → Account and password → Two-factor authentication) — leave blank if 2FA is off. Lets the bridge compute the current 2FA code itself on auto-login instead of prompting a human each time. Not usable for FIDO2/security-key-only 2FA — switch that account to TOTP first, or do one interactive bridge login."
+      },
+      {
+        "name": "protonMailboxPassword",
+        "label": "Proton mailbox password (optional)",
+        "type": "password",
+        "required": false,
+        "description": "ONLY for accounts with two-password mode enabled (Settings → Account and password) — a separate second password protecting the mailbox itself, distinct from the account login password. Leave blank for single-password accounts (the default)."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "proton-account",
+        "name": "{{name}} Proton account credentials",
+        "value": "{{protonCredentialsJson}}",
+        "type": "api_key",
+        "service": "proton",
+        "description": "Proton ACCOUNT credentials (email/password/totpSeed/mailboxPassword, JSON-encoded; last two optional) used by the headless bridge to auto-log-in on boot. Not the Bridge-generated IMAP/SMTP password."
+      }
+    ],
+    "tools": [
+      {
+        "name": "proton",
+        "kind": "external",
+        "description": "Proton Mail via a locally-run Proton Bridge (self-host path). The bridge decrypts Proton's end-to-end-encrypted mail and exposes plain IMAP/SMTP on localhost; this tool's credentialRef is remapped to the runtime vault://<id> at apply time so the Proton account credentials resolve server-side and the bridge auto-logs-in with them on boot. Inbound is polled from the bridge's IMAP mailbox and landed via the same inbound-recorder substrate as other channels (v1 is inbound-only; SMTP send is a future outbound capability). Connection host/ports and poll cadence are bridge-local env (the bridge talks to a fixed 127.0.0.1 Proton Bridge) — only mailbox/backfill/sender-filters here are pod-editable behavioral config. MUTUAL EXCLUSIVITY: do not also run a Proton-forward-to-Mailgun rule for the same mailbox (see template description) — that double-ingests.",
+        "credentialRef": "proton-account",
+        "executor": "external-agent",
+        "config": {
+          "transport": "bridge",
+          "externalSource": "proton"
+        },
+        "metadata": {
+          "proton": {
+            "mailbox": "INBOX",
+            "backfillDays": 7,
+            "senderAllow": [],
+            "senderDeny": [],
+            "configSchema": [
+              {
+                "key": "mailbox",
+                "label": "Canonical mailbox to poll",
+                "valueType": "string"
+              },
+              {
+                "key": "backfillDays",
+                "label": "Initial backfill window (days)",
+                "valueType": "number"
+              },
+              {
+                "key": "senderAllow",
+                "label": "Sender allowlist (emails/domains)",
+                "valueType": "json"
+              },
+              {
+                "key": "senderDeny",
+                "label": "Sender blocklist (emails/domains)",
+                "valueType": "json"
+              }
+            ]
+          }
+        }
+      }
+    ],
+    "skills": [],
+    "provides": [],
+    "playbooks": [
+      {
+        "name": "Proton — Draft Reply",
+        "description": "Draft a reply to a client's most recent inbound Proton email and FILE IT AS A PROPOSAL for the human to approve — never auto-sent. Runs as an is-agent so the send routes through the governed external-send door (the client-comms firewall guarantees an agent reply to a client channel is PROPOSED, not mirrored). On-demand for any client with a bound Proton channel; approving the proposal delivers the reply out over the bridge's SMTP with the correct RFC reply headers. This is the sovereign, proposal-gated counterpart to a hosted mail client's 'AI draft' — the draft is byte-identical to what sends on approval.",
+        "goalTemplate": "Draft a reply to the most recent inbound Proton email from the client {client}, then send it — your external-send tool FILES IT AS A PROPOSAL for a human to review and approve; it is NEVER auto-sent. Optional steer: {guidance}.\n\n1. Find the client's bound Proton email channel and read the latest inbound thread (the subject and the specific message you are replying to). If the client has no Proton channel or no inbound mail, STOP and say so — never invent a thread.\n2. Draft a reply IN THE CLIENT'S LANGUAGE and register/tone, grounded ONLY in the thread and the client's known context. Address what they actually asked. Never fabricate commitments, dates, numbers, or facts you cannot verify — leave those for the human to fill.\n3. Send the drafted reply on that Proton channel using your external-send tool. This FILES A PROPOSAL — a 'proposed' result is SUCCESS, awaiting the human's approval; do NOT claim the email was sent. On approval the bridge delivers it over SMTP.\n4. If anything is ambiguous or high-stakes, note it for the human rather than guessing.",
+        "params": [
+          {
+            "name": "client",
+            "label": "Client",
+            "type": "entity",
+            "required": true,
+            "description": "The client entity whose latest inbound Proton email you are replying to (the session subject). Already resolved — never created here."
+          },
+          {
+            "name": "guidance",
+            "label": "Reply guidance",
+            "type": "text",
+            "required": false,
+            "description": "Optional steer for the reply (angle, key points, tone). Leave blank to let the agent draft from the thread alone."
+          }
+        ],
+        "subjectProfile": {
+          "profileSlug": "company"
+        },
+        "channelSpec": {
+          "type": "THREAD",
+          "aiReactionMode": "only_mentioned"
+        },
+        "executor": "is-agent",
+        "status": "active"
+      }
+    ],
+    "automations": [
+      {
+        "name": "Proton — Inbox Triage (unbound mail)",
+        "description": "EVENT-DRIVEN. When a NEW Proton email lands on an UNBOUND channel (a sender not yet linked to a client), classify it with ONE AI pass and post a one-line digest to this automation's OWN run channel so untracked mail is visible instead of silent. Gated to provider=proton AND unbound (entityId empty), so it never overlaps the BOUND-client re-synthesis that arch-client-intelligence already runs on the same event (no double-triage). COMMON CASE NEEDS NOTHING: a client whose email is on file binds automatically (the `email` identity signal is derived from the entity's email property), so their mail is BOUND and handled by arch — this catches only the not-yet-linked tail. Seeded DRAFT: it runs a paid AI pass per unbound Proton message, so activate it after a dogfood run (same convention as the arch/Stellar AI automations). NOT a second inbound door or triage engine — it reads the landed message off the shared `external_message.received` event, the same spine every channel uses.",
+        "triggerType": "event",
+        "triggerConfig": {
+          "eventPattern": "external_message.received.completed"
+        },
+        "status": "draft",
+        "metadata": {
+          "kind": "proton-inbox-triage",
+          "pairsWith": "proton"
+        },
+        "flowDefinition": {
+          "nodes": [
+            {
+              "id": "trigger",
+              "type": "trigger",
+              "position": {
+                "x": 0,
+                "y": 0
+              },
+              "data": {
+                "triggerType": "event",
+                "label": "New inbound external message",
+                "config": {
+                  "eventPattern": "external_message.received.completed"
+                }
+              }
+            },
+            {
+              "id": "proton-gate",
+              "type": "condition",
+              "position": {
+                "x": 0,
+                "y": 120
+              },
+              "data": {
+                "label": "Only Proton mail",
+                "expression": "trigger.payload.data.provider === \"proton\"",
+                "_note": "`external_message.received` fires for EVERY inbound provider (Discord/Unipile/Proton). The event data carries `provider` (= the connector's provider string, 'proton' here), so a bare-path + operator + quoted-literal condition keeps this automation to Proton mail only. triggerConfig.filters is equality-only on top-level keys and cannot reach into `data`, so the provider gate lives here in-flow. Chained (not `&&`-combined with the unbound gate) because the condition grammar is single-comparison — two condition nodes in series is the supported shape."
+              }
+            },
+            {
+              "id": "unbound-gate",
+              "type": "condition",
+              "position": {
+                "x": 0,
+                "y": 240
+              },
+              "data": {
+                "label": "Only UNBOUND senders (not yet linked to a client)",
+                "expression": "trigger.payload.data.entityId === \"\"",
+                "_note": "`data.entityId` is the bound client entity (null/absent when the channel isn't client-bound). resolveTemplate renders an absent path to \"\", so `=== \"\"` is true for unbound mail and false for a bound client. This is the EXACT COMPLEMENT of arch-client-intelligence's matched-client gate (`entityId !== \"\"`): arch handles bound clients, this handles the unbound tail — no message is triaged twice."
+              }
+            },
+            {
+              "id": "assess",
+              "type": "capability",
+              "position": {
+                "x": 0,
+                "y": 360
+              },
+              "data": {
+                "label": "Classify the unbound email → JSON",
+                "verbId": "ai.generate",
+                "inputMapping": {
+                  "json": "true",
+                  "maxTokens": "300",
+                  "system": "You are a strict data-extraction function that triages a single inbound email from an unrecognized sender. Respond with STRICT JSON and NOTHING else. Never fabricate.",
+                  "prompt": "An email just arrived from a sender not yet linked to any client.\n\nFrom: {{trigger.payload.data.participantName}}\nBody:\n{{trigger.payload.data.content}}\n\nReturn STRICT JSON with EXACTLY these keys and nothing else:\n{\n  \"category\": \"one of: client-inquiry, vendor, newsletter, personal, spam, other\",\n  \"summary\": \"one plain-language sentence on what this email is\",\n  \"relevant\": \"true or false (a STRING, not a boolean): 'true' only when a real person or business appears to be reaching out and a human should look; 'false' for bulk mail, newsletters, and spam\"\n}\nAlways return ALL keys. Use conservative defaults (relevant 'false') when unsure."
+                },
+                "errorHandling": {
+                  "continueOnError": true
+                },
+                "_note": "SINGLE-SUBJECT from the event (no loop node) — the prompt reads the one message off the trigger payload (content is bounded to 4k at the emit site). `relevant` is a STRING ('true'/'false') so the downstream `condition` can test it with an explicit `=== \"true\"` — a bare truthiness check would read the string 'false' as truthy (the documented gate-fail-open trap). Mirrors arch-client-intelligence's `assess` node (ai.generate json)."
+              }
+            },
+            {
+              "id": "relevant-gate",
+              "type": "condition",
+              "position": {
+                "x": 0,
+                "y": 480
+              },
+              "data": {
+                "label": "Only post when the email looks worth a human's attention",
+                "expression": "steps.assess.output.relevant === \"true\"",
+                "_note": "Bare-path + operator + quoted literal (the correct, non-fail-open condition grammar). Newsletters/spam ('false') are silently dropped — that IS the triage; the digest stays signal, not noise."
+              }
+            },
+            {
+              "id": "post",
+              "type": "output",
+              "position": {
+                "x": 0,
+                "y": 600
+              },
+              "data": {
+                "label": "Post one line into the run channel (TARGETLESS)",
+                "outputType": "channel_message",
+                "config": {
+                  "content": "**{{steps.assess.output.category}}** — {{steps.assess.output.summary}}\nFrom {{trigger.payload.data.participantName}} · not yet linked to a client",
+                  "metadata": {
+                    "automationMessage": true,
+                    "kind": "proton-inbox-triage"
+                  }
+                },
+                "errorHandling": {
+                  "continueOnError": true
+                },
+                "_note": "TARGETLESS on purpose (no channelId/channelType): the executor posts to this automation's OWN run channel, so an unbound-mail digest never lands in a client-facing or team channel by accident. Same posture as mail-feed's shadow post. NOT a reply and NOT a client-facing message — it is an internal triage line for the operator."
+              }
+            }
+          ],
+          "edges": [
+            {
+              "id": "e-trigger-proton",
+              "source": "trigger",
+              "target": "proton-gate"
+            },
+            {
+              "id": "e-proton-unbound",
+              "source": "proton-gate",
+              "target": "unbound-gate",
+              "sourceHandle": "yes"
+            },
+            {
+              "id": "e-unbound-assess",
+              "source": "unbound-gate",
+              "target": "assess",
+              "sourceHandle": "yes"
+            },
+            {
+              "id": "e-assess-relevant",
+              "source": "assess",
+              "target": "relevant-gate"
+            },
+            {
+              "id": "e-relevant-post",
+              "source": "relevant-gate",
+              "target": "post",
+              "sourceHandle": "yes"
+            }
+          ]
+        }
+      }
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/replicate-rvm.capability.json

@@ -0,0 +1,97 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "replicate-rvm",
+    "name": "Replicate — Video Background Removal",
+    "description": "Cut the person out of a recorded video with Robust Video Matting on Replicate: returns the matte and the person's own colours as videos, for putting a new background behind them. Each run bills your Replicate account. Replicate deletes the results after about an hour, so download them. Needs a Replicate API token.",
+    "tags": ["capability"],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "replicate-rvm",
+    "name": "Replicate Video Background Removal",
+    "description": "Serves the edit_video intent with Robust Video Matting (RVM, arielreplicate/robust_video_matting, version 73d2128a pinned) on Replicate's predictions API (base https://api.replicate.com/v1, Authorization: Bearer <token>). RVM is a recurrent model built for video: it keeps memory between frames, so the matte does not flicker the way a per-frame image model does. Its weights are GPL-3.0; here they run only as Replicate's hosted service, nothing is distributed. Stores the Replicate token in the vault, registers one HTTP API tool, and seeds two code verbs. replicate_rvm_matte (edit_video, a write that bills the account) takes { video: https URL } or { videoFile: a pod file id, signed by the pod at run time (file:url) }, plus outputs?: ['alpha','foreground','green-screen'] (default alpha + foreground) and starts one prediction per output: the alpha matte (white = the person) and the foreground (the model's own colour for the person, edges included, to composite without the old room's colour in the hair). replicate_rvm_result (fetch_record, read-only) reads them by id. The matte verb declares inputMap { video: $.video }, so a pod app's edit_video action (one input per intent) reaches it with the default outputs. GOTCHA: a skill isolate has no timer, so a verb cannot poll: the matte verb starts every prediction but the last without waiting and the last with Prefer: wait=60 (Replicate's maximum), so they run side by side, then reads the others once. A take that is not done by then comes back { status: 'processing', predictionIds, next: { verbId: 'replicate_rvm_result', parameters } }: run next every 30-60 s, never start the matte again. GOTCHA: Replicate deletes outputs about an hour after a prediction ends; download them at once. The video URL must be reachable by Replicate (a signed pod file URL is). PRECONDITION: a Replicate account with billing and an API token (https://replicate.com/account/api-tokens). Pass it as `replicateApiToken`.",
+    "params": [
+      {
+        "name": "replicateApiToken",
+        "label": "Replicate API token",
+        "type": "text",
+        "required": true,
+        "description": "The Replicate API token (https://replicate.com/account/api-tokens). Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "replicateApiTokenSecret",
+        "name": "{{name}} Replicate API token",
+        "value": "{{replicateApiToken}}",
+        "type": "api_key",
+        "description": "Replicate API token for the replicate_api connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "replicate_api",
+        "kind": "api",
+        "description": "Authenticated HTTP access to Replicate's predictions API (https://api.replicate.com/v1). The applier injects the vaulted token into the Authorization header as `Bearer <token>`; its credentialRef is remapped to the runtime vault://<id> at apply time.",
+        "credentialRef": "replicateApiTokenSecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.replicate.com/v1",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "replicate_rvm_matte",
+        "intent": "edit_video",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Cuts the person out of a video with Robust Video Matting on Replicate (bills the Replicate account). Args: { video?: string (https URL of the video, no credentials) OR videoFile?: a pod file entity id (the pod signs it at run time; pass exactly one), outputs?: string[] (any of 'alpha', 'foreground', 'green-screen'; default ['alpha', 'foreground']) }. Only these args reach Replicate. Returns { status: 'succeeded' | 'processing', alphaUrl?, foregroundUrl?, greenScreenUrl?, predictions: [{ output, id, status, url, error }], predictionIds, next }. status 'processing' means a prediction was still running after about a minute: run next (replicate_rvm_result with the same predictionIds) every 30-60 s; never run this verb again for the same video. A failed prediction fails the run with its error. Replicate deletes the videos about an hour after they finish: download them at once.",
+        "requires": ["replicate_api"],
+        "executionMode": "async",
+        "timeoutSeconds": 150,
+        "metadata": {
+          "verbType": "write"
+        },
+        "parameters": {
+          "video": "string?",
+          "videoFile": "file:url?",
+          "outputs": "array?"
+        },
+        "inputMap": {
+          "params": {
+            "video": "$.video"
+          }
+        },
+        "code": "// Cut the person out of a video with Robust Video Matting on Replicate\n// (side-effecting write: starts billed predictions on the person's Replicate\n// account). Executor wraps this body as (async (args, context) => { <code> });\n// use args directly and `return`. callProvider(tool, method, path, body?, opts?)\n// resolves the replicate_api tool by NAME, injects the vaulted token as\n// Authorization: Bearer <token>, and uses the tool's config.baseUrl =\n// https://api.replicate.com/v1.\n//\n// LONG RUNS. The isolate has no timer, so this verb cannot poll. It starts one\n// prediction per output; all but the last start without waiting, the last\n// starts with `Prefer: wait=60` (Replicate holds that request up to 60 s, its\n// maximum), so the predictions run side by side while it waits. Then it reads\n// the earlier ones once. Whatever is not finished comes back as status\n// 'processing' with `next`: the read verb replicate_rvm_result and its\n// parameters, to run later. Never start the predictions again to wait.\n//\n// INPUTS: only `video` OR `videoFile`, and `outputs`, are read; nothing else\n// reaches Replicate. `video` is an https URL (the edit_video intent's input).\n// `videoFile` is a pod file: the caller passes its file entity id and the pod\n// swaps it for a fresh signed URL at run time (`file:url`, valid 6 h for an\n// async verb, so a cold Replicate start can still fetch it). That URL is never\n// echoed in an error or returned. The model version is pinned, so a run is\n// reproducible and a caller cannot point the token at another model.\nconst VERSION = '73d2128a371922d5d1abf0712a1d974be0e4e2358cc1218e4e34714767232bac';\nconst OUTPUT_TYPES = { alpha: 'alpha-mask', foreground: 'foreground-mask', 'green-screen': 'green-screen' };\nconst URL_KEYS = { alpha: 'alphaUrl', foreground: 'foregroundUrl', 'green-screen': 'greenScreenUrl' };\nif (args && args.input_video !== undefined) throw new Error('replicate_rvm_matte: pass video, not input_video');\nif (args && args.output_type !== undefined) throw new Error('replicate_rvm_matte: pass outputs, not output_type');\nconst HTTPS = /^https:\\/\\/[^\\s\\/?#@]+([\\/?#][^\\s]*)?$/i;\nconst given = String(args?.video ?? '').trim();\nconst fromPod = args?.videoFile === undefined || args?.videoFile === null ? '' : String(args.videoFile).trim();\nif (given && fromPod) throw new Error('replicate_rvm_matte: pass video (an https URL) or videoFile (a pod file), not both');\nif (!given && !fromPod) throw new Error('replicate_rvm_matte: video (an https URL) or videoFile (a pod file) is required');\n// Public https only, no userinfo (user:pass@), no data:/file:/vault: refs.\nif (given && (given.length > 2048 || !HTTPS.test(given))) {\n  throw new Error('replicate_rvm_matte: video must be an https URL without credentials (got ' + given.slice(0, 80) + ')');\n}\n// The pod signs videoFile; anything but a signed https URL means it was not swapped.\nif (fromPod && (fromPod.length > 4096 || !HTTPS.test(fromPod))) {\n  throw new Error('replicate_rvm_matte: videoFile did not arrive as a signed pod file URL; pass the take\\'s file entity id');\n}\nconst video = given || fromPod;\nconst source = given ? 'url' : 'pod-file';\nlet outputs = ['alpha', 'foreground'];\nif (args?.outputs !== undefined) {\n  if (!Array.isArray(args.outputs) || args.outputs.length === 0) throw new Error('replicate_rvm_matte: outputs must be a non-empty array of alpha, foreground, green-screen');\n  outputs = [];\n  for (const o of args.outputs) {\n    const k = String(o ?? '').trim();\n    if (!Object.prototype.hasOwnProperty.call(OUTPUT_TYPES, k)) throw new Error('replicate_rvm_matte: unknown output ' + k.slice(0, 40) + ' (use alpha, foreground or green-screen)');\n    if (!outputs.includes(k)) outputs.push(k);\n  }\n}\n\nconst FAILED = ['failed', 'canceled', 'aborted'];\nconst ID_RE = /^[a-z0-9]{8,64}$/;\nconst shape = (output, p) => {\n  const status = String(p?.status ?? '');\n  const out = Array.isArray(p?.output) ? p.output[0] : p?.output;\n  if (status === 'succeeded') {\n    if (typeof out !== 'string' || !/^https:\\/\\//i.test(out)) return { output, id: p.id, status: 'failed', url: null, error: 'the prediction succeeded with no video URL' };\n    return { output, id: p.id, status: 'succeeded', url: out, error: null };\n  }\n  if (FAILED.includes(status)) return { output, id: p.id, status: 'failed', url: null, error: String(p?.error ?? status).slice(0, 300) };\n  return { output, id: p.id, status: 'processing', url: null, error: null };\n};\nconst ok = (res) => typeof res?.status === 'number' && res.status >= 200 && res.status < 300;\n\nconst predictions = [];\nfor (let i = 0; i < outputs.length; i++) {\n  const last = i === outputs.length - 1;\n  const res = await callProvider(\n    'replicate_api',\n    'POST',\n    '/predictions',\n    { version: VERSION, input: { input_video: video, output_type: OUTPUT_TYPES[outputs[i]] } },\n    last ? { headers: { Prefer: 'wait=60' } } : undefined,\n  );\n  // The capability-execution gate may return a PROPOSAL envelope instead of\n  // executing: that proposal IS the record. Report what already started.\n  if (res?.proposed === true) {\n    return { success: false, proposed: true, proposalId: res?.proposalId ?? null, started: predictions.map((p) => p.id) };\n  }\n  const body = res?.body ?? {};\n  if (!ok(res) || typeof body.id !== 'string' || !ID_RE.test(body.id)) {\n    const detail = typeof body?.detail === 'string' ? ': ' + body.detail.slice(0, 200) : '';\n    throw new Error('replicate_rvm_matte: Replicate refused the ' + outputs[i] + ' prediction (status ' + (res?.status ?? 'unknown') + ')' + detail);\n  }\n  predictions.push(shape(outputs[i], body));\n}\n// The earlier predictions ran while the last one waited: read each once.\nfor (let i = 0; i < predictions.length - 1; i++) {\n  if (predictions[i].status !== 'processing') continue;\n  const res = await callProvider('replicate_api', 'GET', '/predictions/' + predictions[i].id);\n  if (ok(res) && res.body?.id === predictions[i].id) predictions[i] = shape(predictions[i].output, res.body);\n}\n\nconst failed = predictions.filter((p) => p.status === 'failed');\nif (failed.length) {\n  throw new Error('replicate_rvm_matte: ' + failed.map((p) => p.output + ' prediction ' + p.id + ' failed: ' + p.error).join('; '));\n}\nconst predictionIds = predictions.map((p) => p.id);\nconst status = predictions.some((p) => p.status === 'processing') ? 'processing' : 'succeeded';\nconst urls = {};\nfor (const p of predictions) if (p.url) urls[URL_KEYS[p.output]] = p.url;\nreturn {\n  success: true,\n  proposed: false,\n  source,\n  status,\n  ...urls,\n  predictions,\n  predictionIds,\n  next: status === 'processing' ? { verbId: 'replicate_rvm_result', parameters: { predictionIds } } : null,\n  note: 'Replicate deletes prediction outputs about an hour after they finish: download the videos now.',\n};"
+      },
+      {
+        "name": "replicate_rvm_result",
+        "intent": "fetch_record",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Reads Robust Video Matting predictions that replicate_rvm_matte started (read-only: nothing is started or billed). Args: { predictionIds: string[] (1-3 ids from replicate_rvm_matte) }. Returns the same shape: { status: 'succeeded' | 'processing', alphaUrl?, foregroundUrl?, greenScreenUrl?, predictions, predictionIds, next }. A failed prediction fails the run with its error; an id that is not an RVM prediction is refused.",
+        "requires": ["replicate_api"],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "metadata": {
+          "readOnly": true
+        },
+        "parameters": {
+          "predictionIds": "array"
+        },
+        "code": "// Read Robust Video Matting predictions started by replicate_rvm_matte (a\n// read: GET only, nothing is billed or started). Executor wraps this body as\n// (async (args, context) => { <code> }). callProvider resolves the\n// replicate_api tool by NAME and injects the vaulted token.\n//\n// Run it while replicate_rvm_matte's result says status 'processing', with the\n// predictionIds it returned (its `next`), every 30-60 s. Only predictions of\n// the pinned RVM version are read: another id on the same token is refused.\nconst VERSION = '73d2128a371922d5d1abf0712a1d974be0e4e2358cc1218e4e34714767232bac';\nconst OUTPUTS = { 'alpha-mask': 'alpha', 'foreground-mask': 'foreground', 'green-screen': 'green-screen' };\nconst URL_KEYS = { alpha: 'alphaUrl', foreground: 'foregroundUrl', 'green-screen': 'greenScreenUrl' };\nif (args && args.prediction_ids !== undefined) throw new Error('replicate_rvm_result: pass predictionIds, not prediction_ids');\nif (!Array.isArray(args?.predictionIds) || args.predictionIds.length === 0) {\n  throw new Error('replicate_rvm_result: predictionIds is required (the ids replicate_rvm_matte returned)');\n}\nconst ids = [];\nfor (const raw of args.predictionIds) {\n  const id = String(raw ?? '').trim();\n  if (!/^[a-z0-9]{8,64}$/.test(id)) throw new Error('replicate_rvm_result: ' + id.slice(0, 40) + ' is not a Replicate prediction id');\n  if (!ids.includes(id)) ids.push(id);\n}\nif (ids.length > 3) throw new Error('replicate_rvm_result: predictionIds takes at most 3 ids');\n\nconst FAILED = ['failed', 'canceled', 'aborted'];\nconst predictions = [];\nfor (const id of ids) {\n  const res = await callProvider('replicate_api', 'GET', '/predictions/' + id);\n  const p = res?.body ?? {};\n  if (!(typeof res?.status === 'number' && res.status >= 200 && res.status < 300) || p.id !== id) {\n    throw new Error('replicate_rvm_result: could not read prediction ' + id + ' (status ' + (res?.status ?? 'unknown') + ')');\n  }\n  if (p.version !== VERSION) throw new Error('replicate_rvm_result: prediction ' + id + ' is not a Robust Video Matting prediction');\n  const output = OUTPUTS[p?.input?.output_type ?? 'green-screen'] ?? null;\n  const status = String(p.status ?? '');\n  const out = Array.isArray(p.output) ? p.output[0] : p.output;\n  if (status === 'succeeded' && typeof out === 'string' && /^https:\\/\\//i.test(out)) predictions.push({ output, id, status: 'succeeded', url: out, error: null });\n  else if (status === 'succeeded') predictions.push({ output, id, status: 'failed', url: null, error: 'the prediction succeeded with no video URL' });\n  else if (FAILED.includes(status)) predictions.push({ output, id, status: 'failed', url: null, error: String(p.error ?? status).slice(0, 300) });\n  else predictions.push({ output, id, status: 'processing', url: null, error: null });\n}\n\nconst failed = predictions.filter((p) => p.status === 'failed');\nif (failed.length) {\n  throw new Error('replicate_rvm_result: ' + failed.map((p) => p.output + ' prediction ' + p.id + ' failed: ' + p.error).join('; '));\n}\nconst status = predictions.some((p) => p.status === 'processing') ? 'processing' : 'succeeded';\nconst urls = {};\nfor (const p of predictions) if (p.url && p.output) urls[URL_KEYS[p.output]] = p.url;\nreturn {\n  success: true,\n  status,\n  ...urls,\n  predictions,\n  predictionIds: ids,\n  next: status === 'processing' ? { verbId: 'replicate_rvm_result', parameters: { predictionIds: ids } } : null,\n  note: 'Replicate deletes prediction outputs about an hour after they finish: download the videos now.',\n};"
+      }
+    ],
+    "provides": ["edit_video", "fetch_record"]
+  },
+  "dependencies": []
+}

package/capabilities/research-methods.capability.json

@@ -0,0 +1,57 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "research-methods",
+    "name": "Research — Method Skills",
+    "description": "Four research methods for agents: rank sources, weigh evidence into a finding, map findings onto a concept graph, and structure open questions as decisions. Used by the Research and Decision Analysis workspaces; pairs with Exa for web search.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "research-methods",
+    "name": "Research — Method Skills",
+    "description": "The research method bundle: four instruction skills (prompt/doc skills injected into the agent's turn — no sandboxed code, no connector calls) that teach the agent HOW to do research well, not just gather links. source-triage builds the full ranked evidence surface and keeps the rejected sources (nothing lost); evidence-synthesis weighs supporting vs contradicting sources into a calibrated finding; concept-cartography places findings onto the field/concept knowledge map and dedups; ibis-decision-analysis structures an open question as a decision with its arguments and roads-not-taken preserved. These are pure know-how — they shape WHAT the agent writes into the research graph. Every write stays proposal-gated and reversible. Granted by the research-base and research-decision workspace templates; pairs with a web-search tool (exa) for source gathering.",
+    "params": [],
+    "vault": [],
+    "tools": [],
+    "skills": [
+      {
+        "name": "source-triage",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Gather sources widely, rank them by credibility/quality, and KEEP the rejected ones with a reason (nothing lost). Feeds supports/contradicts links to a hypothesis. Pairs with a web-search tool.",
+        "requires": [
+          "exa_search"
+        ],
+        "code": "# Source Triage\n\nYou are gathering and ranking the sources for a piece of research. The point is not to find \"the answer\" and stop — it is to build the FULL evidence surface and rank it honestly, so the reasoning that follows can be trusted and re-checked later. A researcher who keeps only the sources that agreed with them has hidden their work.\n\n## Inputs you are given\n- The question or hypothesis under investigation.\n- Whatever the agent can retrieve (web search results, provided documents, the pod's existing sources).\n\n## How to triage\n1. **Gather widely first, judge second.** Pull more candidate sources than you'll cite — including ones you expect to disagree with. Breadth before verdict.\n2. **Classify the source TYPE** honestly: paper, dataset, book, article, blog, forum, video, other. Type shapes how much weight it can bear.\n3. **Assign a credibility band** — high / medium / low / unknown — from concrete signals, not vibes: primary vs secondary, peer review, author expertise, recency, methodology, corroboration by independent sources, and conflicts of interest. State the signal, don't just assert the band.\n4. **KEEP everything, mark the rejects.** A source you considered and decided NOT to rely on is still recorded — as a source with `status: rejected` and a one-line `whyRejected` (out of date, unsupported claim, primary source contradicts it, low-quality outlet). Never silently drop it. The rejected pile is part of the evidence.\n5. **Cited = the ones you actually rely on** (`status: cited`); **considered = still in play** but not yet load-bearing.\n\n## Hard rules\n- Never inflate a blog or a single forum post to \"high\" credibility because it's convenient.\n- When two credible sources conflict, keep BOTH and record the conflict — do not pick one and delete the other.\n- Never invent a source, a URL, or an author. If you can't verify it, band is `unknown`.\n\n## Output\nFor each source, propose a `source` entity with: title, url, author, sourceType, credibilityBand, an optional qualityScore (0–100), status (cited | considered | rejected), and whyRejected when rejected. Link cited/considered sources to the hypothesis they bear on with `supports` or `contradicts`. Every write is proposal-gated."
+      },
+      {
+        "name": "evidence-synthesis",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Weigh supporting vs contradicting sources into a finding with honestly calibrated confidence, confronting the contradictions rather than hiding them. Pure know-how.",
+        "code": "# Evidence Synthesis\n\nYou are turning a ranked set of sources into a FINDING — a validated (or provisional) claim with calibrated confidence. This is the step where evidence becomes knowledge. The danger is false certainty: a confident finding built on weak or one-sided evidence is worse than an honest \"we don't know yet\".\n\n## Inputs you are given\n- A question or hypothesis.\n- The triaged sources bearing on it — those that support it and those that contradict it, with their credibility bands.\n\n## How to synthesize\n1. **Weigh, don't count.** Three low-credibility blogs do not outweigh one strong primary source. Give weight by credibility band and directness of evidence, not by headcount.\n2. **Confront the contradictions.** Explicitly account for the sources that disagree. A finding that ignores its counter-evidence isn't validated — it's asserted. If the contradiction is unresolved, say so and lower confidence.\n3. **Separate what's established from what's inferred.** State the claim at the strength the evidence actually supports — not stronger. Prefer a narrow claim you can stand behind over a broad one you can't.\n4. **Calibrate confidence honestly** (0–1): high (>0.8) only with strong, corroborated, uncontested evidence; provisional (~0.4–0.7) when evidence is real but partial or mixed; low (<0.4) when it's suggestive at best. If the evidence is too thin, do NOT emit a finding — record what's still needed instead.\n5. **Cite your grounds.** Every finding links to the specific sources it rests on with `supported_by`, and to the research it came from with `derived_from`.\n\n## Hard rules\n- Never round confidence up to make the finding feel conclusive.\n- Never drop the dissenting evidence to make the story clean.\n- A finding with no source link is an opinion, not a finding — don't emit it.\n\n## Output\nPropose a `finding` entity: claim (stated at the supported strength), confidence (0–1), evidenceSummary (how the sources were weighed, including the contradictions), status (validated | provisional | retracted). Link it `supported_by` its sources and `derived_from` the research, and `about` the concept(s) it concerns. Proposal-gated."
+      },
+      {
+        "name": "concept-cartography",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Place findings/concepts onto the field/concept knowledge map (part_of, overlaps_with, prerequisite_of), resolving duplicates before creating. Pure know-how.",
+        "code": "# Concept Cartography\n\nYou are placing what was learned onto the knowledge MAP — the graph of fields and concepts — so a finding isn't an island but a located point a researcher can navigate to and build from. Good cartography is what turns a pile of notes into a second brain: it reveals what connects to what, and what to learn next.\n\n## Inputs you are given\n- A concept, field, or finding to place.\n- The existing fields and concepts already in the pod (always check before creating).\n\n## How to map\n1. **Resolve before you create.** Search existing `field` and `concept` entities first — \"Bayesian inference\", \"gradient descent\", \"qualia\" should exist ONCE. Match on the real idea, not the exact spelling, before minting a duplicate.\n2. **Locate the concept in its field(s)** with `part_of` — and note when a concept genuinely spans several fields (e.g. \"information theory\" is part_of both mathematics and AI). Cross-field concepts are the interesting ones; don't force a single home.\n3. **Wire the field overlaps.** When two fields share territory, link them `overlaps_with` (AI overlaps_with mathematics, philosophy, cognitive science). This is the map's connective tissue — the thing that lets the system suggest \"you're studying X; here's its neighbour Y\".\n4. **Chain the prerequisites.** When understanding concept A genuinely requires concept B first, link `prerequisite_of` (linear algebra prerequisite_of gradient descent). Use it for real dependencies, not loose association — that's what `relates_to` is for.\n5. **Attach the finding.** Link the finding `about` the concept(s) it concerns, so the map shows not just ideas but what we've actually established about them.\n\n## Hard rules\n- Never create a second entity for a concept that already exists — extend the existing one.\n- Don't invent a prerequisite chain to look rigorous; only link dependencies you can justify.\n- A field/concept with no links is barely on the map — always place at least one edge.\n\n## Output\nPropose `field`/`concept` entities (only when they don't already exist) and the edges above: `part_of`, `overlaps_with`, `prerequisite_of`, `relates_to`, `about`. Proposal-gated."
+      },
+      {
+        "name": "ibis-decision-analysis",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Structure an open question as a decision via IBIS: options as hypotheses, arguments as supporting/contradicting sources, and a decision that preserves the roads-not-taken and why. Pure know-how.",
+        "code": "# Decision Analysis (IBIS)\n\nYou are structuring an open question as a DECISION using the IBIS method (Issue → Positions → Arguments) so the reasoning behind the recommendation is fully captured — not just the answer. The value is that six months later, anyone can see which options were considered, what argued for and against each, and why the chosen one won. A recommendation with no visible argument is just an assertion.\n\n## Inputs you are given\n- The question / issue to decide.\n- The research so far — hypotheses (candidate positions) and the sources bearing on them.\n\n## How to analyze\n1. **State the issue sharply.** One decision, framed so the options are genuinely mutually exclusive. A fuzzy issue produces a fuzzy decision.\n2. **Enumerate the real options** as `hypothesis` entities — including the status-quo / do-nothing option. Two options is often a false binary; look for the third.\n3. **Argue each side with EVIDENCE, not preference.** For every option, gather the sources that `support` it and those that `contradict` it (use Source Triage — keep the rejected ones too). An argument with no source behind it is weak and should be marked as such.\n4. **Weigh against explicit criteria.** Name the criteria that matter for THIS decision (cost, reversibility, risk, time, evidence strength) before scoring — so the weighing is honest, not retrofitted to a preferred answer.\n5. **Record the decision, not just the winner.** The recommendation becomes a `decision` entity whose `rationale` explains why it won and whose `alternatives` field preserves the options that lost and WHY. The losing options stay linked — the reasoning is the deliverable.\n6. **State what would change your mind.** Note the evidence that, if it appeared, would flip the decision. This is what makes it revisitable rather than final.\n\n## Hard rules\n- Never present one option as obvious if the evidence is genuinely mixed — surface the trade-off.\n- Never discard the rejected options or the counter-arguments; `alternatives` must record them.\n- Confidence in the recommendation is bounded by the weakest link in its evidence — don't overstate it.\n\n## Output\nPropose: `hypothesis` entities for the options (with `stance`), `source` links (`supports`/`contradicts`) for the arguments, and a `decision` entity with summary, rationale, alternatives (the roads not taken + why), and decisionStatus. Link the decision to the question it resolves. Proposal-gated."
+      }
+    ],
+    "provides": []
+  },
+  "dependencies": []
+}