@synap-core/workspace-templates 0.12.0 → 0.24.0

package/capabilities/mail-feed.capability.json

@@ -0,0 +1,277 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "mail-feed",
+    "name": "Mail Feed — Gmail Triage",
+    "description": "Every two hours, checks recent Gmail, skips blocked senders, sorts the rest and posts one line per relevant email to its own channel. Needs the Google Workspace connector.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "mail-feed",
+    "name": "Mail Feed",
+    "description": "Config-first mail feed: every 2 hours, search recent Gmail, drop denied senders, triage the rest with AI, and post one line per relevant email into the automation's own run channel. This is the SHADOW form of the bespoke run-mail-feed worker (packages/api/src/services/mail-feed/run-mail-feed.ts) — same verb pipeline (gmail_search -> ai.triage -> post), expressed purely as an automation flow so it can be dogfooded for parity BEFORE the live worker is retired. Because the output channel_message is TARGETLESS it posts to this automation's run channel, so it never collides with the live worker's Discord-bound feed channel. POST-SIGNOFF CUTOVER (do NOT do now): retarget the `post` node to the real team channel via a `channel.resolve` -> channel_message pair (see client-comms-report.capability.json) and delete run-mail-feed.ts + its mail-feed-cron shim.",
+    "params": [],
+    "vault": [],
+    "tools": [],
+    "skills": [],
+    "provides": [],
+    "playbooks": [],
+    "automations": [
+      {
+        "name": "Mail Feed — Shadow",
+        "description": "Every 2h: gmail_search -> deny-gate (not-in) -> ai.triage -> keep relevant -> post one line each into this automation's OWN run channel (shadow-separated from the live worker). Advances a watermark cursor and nudges if the Google connector is dead. Seeded ACTIVE so the cron actually schedules (a draft never gets a nextRunAt). CUTOVER: retarget `post` to the team channel + delete run-mail-feed once parity is confirmed.",
+        "triggerType": "cron",
+        "triggerConfig": {
+          "expression": "0 */2 * * *"
+        },
+        "status": "active",
+        "state": {
+          "gmailQuery": "newer_than:2h",
+          "senderDeny": [],
+          "mutedCategories": [],
+          "lastProcessedMs": 0
+        },
+        "metadata": {
+          "shadowOf": "run-mail-feed",
+          "kind": "mail-feed"
+        },
+        "flowDefinition": {
+          "nodes": [
+            {
+              "id": "trigger",
+              "type": "trigger",
+              "position": {
+                "x": 0,
+                "y": 0
+              },
+              "data": {
+                "triggerType": "cron",
+                "label": "Every 2 hours",
+                "config": {
+                  "expression": "0 */2 * * *"
+                }
+              }
+            },
+            {
+              "id": "gmail-search",
+              "type": "capability",
+              "position": {
+                "x": 0,
+                "y": 120
+              },
+              "data": {
+                "label": "Search recent Gmail",
+                "verbId": "gmail_search",
+                "inputMapping": {
+                  "query": "{{automation.state.gmailQuery}}",
+                  "maxResults": "25"
+                },
+                "_note": "The `newer_than:2h` query window IS the config-expressible dedup for a 2-hourly cron — run-mail-feed's per-email isNewerThanWatermark filter is NOT expressible as a single transform node today (resolveTemplate has no pipe support, the transform `|` split collides inside a filter predicate, gmail_search results carry no `dateMs`, and there is no per-item field-merge pipe). continueOnError so a dead token still reaches the connector health check below instead of aborting the run.",
+                "errorHandling": {
+                  "continueOnError": true
+                }
+              }
+            },
+            {
+              "id": "deny-gate",
+              "type": "transform",
+              "position": {
+                "x": 0,
+                "y": 240
+              },
+              "data": {
+                "label": "Drop denied senders (deny-wins)",
+                "expression": "{{steps.gmail-search.output.results}} | filter:item.from not-in automation.state.senderDeny",
+                "_note": "Ports passesSenderFilters' deny half via the `not-in` membership operator: keep an email when its `from` is NOT in the seeded senderDeny list. The ALLOW half (`senderAllow` = if non-empty, keep only matches) is NOT ported — an `in` filter against an EMPTY allow-list would drop every email, and the conditional 'only when non-empty' is not expressible as one predicate."
+              }
+            },
+            {
+              "id": "triage",
+              "type": "capability",
+              "position": {
+                "x": 0,
+                "y": 360
+              },
+              "data": {
+                "label": "AI triage (relevance + category + summary)",
+                "verbId": "ai.triage",
+                "inputMapping": {
+                  "emails": "{{steps.deny-gate.output.result}}",
+                  "mutedCategories": "{{automation.state.mutedCategories}}"
+                },
+                "errorHandling": {
+                  "continueOnError": true
+                }
+              }
+            },
+            {
+              "id": "relevant-only",
+              "type": "transform",
+              "position": {
+                "x": 0,
+                "y": 480
+              },
+              "data": {
+                "label": "Keep only relevant emails",
+                "expression": "{{steps.triage.output.results}} | filter:item.relevant == 'true'"
+              }
+            },
+            {
+              "id": "mail-loop",
+              "type": "loop",
+              "position": {
+                "x": 0,
+                "y": 600
+              },
+              "data": {
+                "label": "For each relevant email",
+                "iteratorExpression": "steps.relevant-only.output.result",
+                "itemVariable": "email"
+              }
+            },
+            {
+              "id": "post",
+              "type": "output",
+              "position": {
+                "x": 200,
+                "y": 720
+              },
+              "data": {
+                "label": "Post one line into the run channel (TARGETLESS = shadow-separated)",
+                "outputType": "channel_message",
+                "config": {
+                  "content": "**{{loop.item.category}}** — {{loop.item.summary}}\n{{loop.item.suggestedAction}}",
+                  "metadata": {
+                    "automationMessage": true,
+                    "kind": "mail-feed"
+                  }
+                },
+                "_note": "TARGETLESS on purpose: no channelId/channelType, so the executor posts to this automation's OWN run channel — automatic separation from the live worker's Discord-bound feed. Subject/from/gmail-link enrichment (run-mail-feed's buildMailMessage) is NOT ported: it needs a join from the triage result back to the original email by id, which is not expressible in-flow; the triage summary line stands in.",
+                "errorHandling": {
+                  "continueOnError": true
+                }
+              }
+            },
+            {
+              "id": "compute-now",
+              "type": "compute",
+              "position": {
+                "x": -200,
+                "y": 720
+              },
+              "data": {
+                "label": "Run timestamp",
+                "operation": "now"
+              }
+            },
+            {
+              "id": "watermark-ms",
+              "type": "transform",
+              "position": {
+                "x": -200,
+                "y": 840
+              },
+              "data": {
+                "label": "Run timestamp -> epoch ms",
+                "expression": "{{steps.compute-now.output.result}} | to_ms"
+              }
+            },
+            {
+              "id": "set-watermark",
+              "type": "output",
+              "position": {
+                "x": -200,
+                "y": 960
+              },
+              "data": {
+                "label": "Advance the watermark cursor (runs even when all filtered)",
+                "outputType": "set_state",
+                "config": {
+                  "lastProcessedMs": "{{steps.watermark-ms.output.result}}"
+                },
+                "_note": "Ports the atomic single-leaf watermark advance (one key merged via set_state's `state || patch` jsonb). Placed on the main spine (not in the loop) so it advances once per run regardless of how many emails survived — mirroring run-mail-feed advancing past an all-filtered batch. The cursor is recorded for auditability + forward-compat; it is not yet consumed by the query (see gmail-search _note)."
+              }
+            },
+            {
+              "id": "health-check",
+              "type": "capability",
+              "position": {
+                "x": -200,
+                "y": 1080
+              },
+              "data": {
+                "label": "Nudge if the Google connector is dead",
+                "verbId": "connector.health_check",
+                "inputMapping": {
+                  "provider": "google",
+                  "connectorName": "Google Workspace",
+                  "reconnectHint": "Reconnect it in the app (Settings -> Connectors) or run `/connect provider:google` in Discord.",
+                  "probeVerbId": "gmail_search"
+                },
+                "_note": "Ports the connector-health nudge: probes gmail_search and, on an auth error, nudges the operator once per cooldown (deduped on the pod's discord tool) instead of the feed going silently dead."
+              }
+            }
+          ],
+          "edges": [
+            {
+              "id": "e-trigger",
+              "source": "trigger",
+              "target": "gmail-search"
+            },
+            {
+              "id": "e-search",
+              "source": "gmail-search",
+              "target": "deny-gate"
+            },
+            {
+              "id": "e-deny",
+              "source": "deny-gate",
+              "target": "triage"
+            },
+            {
+              "id": "e-triage",
+              "source": "triage",
+              "target": "relevant-only"
+            },
+            {
+              "id": "e-loop",
+              "source": "relevant-only",
+              "target": "mail-loop"
+            },
+            {
+              "id": "e-post",
+              "source": "mail-loop",
+              "target": "post"
+            },
+            {
+              "id": "e-now",
+              "source": "relevant-only",
+              "target": "compute-now"
+            },
+            {
+              "id": "e-ms",
+              "source": "compute-now",
+              "target": "watermark-ms"
+            },
+            {
+              "id": "e-set",
+              "source": "watermark-ms",
+              "target": "set-watermark"
+            },
+            {
+              "id": "e-health",
+              "source": "set-watermark",
+              "target": "health-check"
+            }
+          ]
+        }
+      }
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/mailgun.capability.json

@@ -0,0 +1,52 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "mailgun",
+    "name": "Mailgun Inbound Email",
+    "description": "Brings client emails into Synap: Mailgun forwards incoming mail to your pod, which verifies it and files each message under the matching client. Also works for Proton Mail via auto-forward. Inbound only. Needs a Mailgun inbound route and webhook signing key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "mailgun",
+    "name": "Mailgun Inbound Email",
+    "description": "Client emails land in the pod's channel/message substrate, queryable by the AI (The Arch Wave 5). Registers a Mailgun HTTP webhook-signing key in the vault (NOT an SMTP send credential — v1 is inbound-only) plus a minimal `mailgun` tool row so an outbound send-as capability can be layered on later without a second connector. The actual ingestion is a BESPOKE pod route (POST /api/webhooks/mailgun/:token, not a generic skill) because it has to parse Mailgun's multipart 'Parsed' inbound payload and verify Mailgun's own timestamp+token HMAC scheme before landing the email as a channel message via recordInboundMessage. ALSO COVERS PROTON MAIL: a Proton user sets an auto-forward rule from their Proton inbox to the Mailgun-provisioned catch-all inbound address, so a Proton client's email reaches the same pipeline as a native Mailgun route address. PRECONDITION: a Mailgun account with an inbound Route configured to forward to POST https://<pod>/api/webhooks/mailgun/<token>, and the account's HTTP webhook signing key (Sending -> Webhooks -> HTTP webhook signing key, shared across all webhook types). Pass it as `mailgunSigningKey`. INBOUND WEBHOOK: Mailgun POSTs multipart/form-data per delivered message (sender, recipient, subject, body-plain, stripped-text, Message-Id, From, Reply-To); the pod verifies `signature == hex(HMAC-SHA256(key=signingKey, msg=timestamp+token))` fail-closed, dedups on Message-Id, resolves the sender's email via strong-signal identity resolution to an existing client entity (one channel PER CLIENT, not per thread) — falling back to the sender email itself (unlinked review-queue channel) when unresolved — and lands the message via recordInboundMessage. FORWARDING LIMITATION: a Proton forward normally preserves the `From` header even though the envelope `sender` is rewritten to the forwarding relay, so the mapper prefers From > Reply-To > envelope sender; a forward that also rewrites From (e.g. SRS/'resend as new') cannot be attributed and lands unlinked. The webhook config is provisioned at install/config time (NOT template-seeded) under `tools.metadata.mailgun.webhook = { token, secretVaultRef, workspaceId?, ownerUserId?, seen:{} }`; the `:token` selects+authorizes the config (unknown -> 404, no enumeration leak).",
+    "params": [
+      {
+        "name": "mailgunSigningKey",
+        "label": "Mailgun HTTP webhook signing key",
+        "type": "text",
+        "required": true,
+        "description": "The Mailgun account's HTTP webhook signing key (Sending -> Webhooks -> HTTP webhook signing key). Used to verify inbound webhook signatures; NOT an API key. Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "mailgunSigningKeySecret",
+        "name": "{{name}} Mailgun webhook signing key",
+        "value": "{{mailgunSigningKey}}",
+        "type": "api_key",
+        "description": "Mailgun HTTP webhook signing key used to verify inbound-route webhook signatures for the mailgun connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "mailgun",
+        "kind": "api",
+        "description": "Mailgun connector. v1 is INBOUND-ONLY: `credentialRef` holds the webhook SIGNING key, consumed directly by the pod's /api/webhooks/mailgun/:token route to verify inbound signatures — it is NOT used for outbound HTTP auth (no skill calls this tool yet). `config.baseUrl` is recorded only as a placeholder for a future outbound send-as skill (Mailgun Messages API, region-specific: https://api.mailgun.net/v3 US or https://api.eu.mailgun.net/v3 EU). GOTCHA for that future skill: Mailgun's outbound API auth is HTTP Basic with username `api` and password = a separate Mailgun API KEY (Settings -> API Keys) — NOT this signing key and NOT wired here; it would need its own vault secret + credentialRef.",
+        "credentialRef": "mailgunSigningKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.mailgun.net/v3"
+        }
+      }
+    ],
+    "skills": [],
+    "provides": []
+  },
+  "dependencies": []
+}