@synap-core/workspace-templates 0.9.4 → 0.10.0

package/src/operations.yaml

@@ -212,6 +212,22 @@ entityLinks:
     targetProfileSlug: company
     type: briefing_about_client
     label: Client
+  # The CRM → Operations handoff edge. A `client` is a ROLE facet on a company
+  # OR a person (foundation's `applicableKinds`), so both endpoint pairs are
+  # declared — a solo-trader client is a person, and the pickup automation must
+  # be able to link its engagement either way.
+  - sourceProfileSlug: engagement
+    targetProfileSlug: company
+    type: engagement_for_client
+    label: Client
+  - sourceProfileSlug: engagement
+    targetProfileSlug: person
+    type: engagement_for_client
+    label: Client
+  - sourceProfileSlug: contract
+    targetProfileSlug: engagement
+    type: contract_for_engagement
+    label: Engagement
 
 # CURATED views — the delivery motion, not one per profile
 views:
@@ -571,3 +587,257 @@ automations:
         - { id: e-write-link, source: write-briefing, target: link-briefing }
         - { id: e-link-resolve, source: link-briefing, target: resolve-team }
         - { id: e-resolve-post, source: resolve-team, target: post-recap }
+
+  # ══════════════════════════════════════════════════════════════════════════
+  # CRM → Operations HANDOFF PICKUP
+  #
+  # The other half of business-developer's "Win and hand off". That flow ends by
+  # attaching the pod-wide `client` role with `handoffStatus`; nothing on the
+  # delivery side ever picked it up, so a won deal became a client and then
+  # nothing happened. This automation is that pickup: once a day it finds
+  # clients marked ready/handed_off that have NO engagement yet, and opens the
+  # delivery shell — a `proposed` engagement plus a `draft` contract.
+  #
+  # WHY THE SHARED `client` SLUG MATTERS: this reads foundation's pod-wide
+  # `client` role. When the CRM wrote a workspace-scoped `crm-client` instead,
+  # this query could not have seen a single handed-off party — the two halves of
+  # the handoff were spelling the same concept differently. Collapsing the fork
+  # is what makes this automation possible at all.
+  #
+  # WHY EVERY NODE TYPE IS WHAT IT IS (loop-body grammar, automation-executor.ts
+  # `LOOP_BODY_NODE_TYPES`): the per-client body may only contain
+  # command / output / condition / skill / capability / playbook_run /
+  # messages_query / query / fetch / transform. `switch`, `entity_read` and
+  # `related_entities` are BOUNDARY types — putting one in the chain would end
+  # the loop body there and silently run the rest ONCE for the whole run. That
+  # is why the two gates are `condition` nodes (per-item continue-semantics) and
+  # why the "does an engagement already exist?" lookup is a `capability`
+  # entity.query rather than a `related_entities` node.
+  #
+  # IDEMPOTENCY is per-client and does not rely on the gate alone:
+  # `dedupeBy: engagement-client` makes a second run for the same client a
+  # no-op SKIP before the governance gate is even reached, and the contract
+  # dedupes on `contract-engagement`. Both keys are real property defs on the
+  # profiles above, not invented ones.
+  #
+  # ── GOVERNANCE, HONESTLY ──────────────────────────────────────────────────
+  # `metadata.governance.forceProposeWrites` is deliberately NOT set here, and
+  # that is not an oversight. That marker is read in exactly ONE place —
+  # `deriveSessionForceProposeGovernance` (synap-backend
+  # `packages/api/src/utils/permission-check.ts`), off a FOCUS SESSION stamped
+  # by `executePlaybookRun`. It is a PLAYBOOK mechanism. A flow automation's
+  # `output/entity_create` goes through `checkAutomationWriteOrPropose`
+  # (packages/jobs/src/utils/automation-governance.ts), which never looks at
+  # automation metadata, so the field would be inert decoration. Worse: the
+  # automation propose path is currently BROKEN end-to-end (proposeAutomationWrite
+  # persists `data` FLAT while the approve executor reads a nested envelope —
+  # documented at automation-executor.ts, "KNOWN PRE-EXISTING BUG"), so forcing
+  # proposals here would produce reviews that throw on approve.
+  #
+  # The reviewability is carried by STATE instead: the engagement is created
+  # `proposed` and the contract `draft`. Nothing is active until a human moves
+  # it. If genuine proposal-gating is wanted, the canonical door is a PLAYBOOK
+  # with `metadata.governance.forceProposeWrites: true` + a `schedule` (the CRM
+  # Hygiene precedent in crm.yaml) — a different, agent-authored design.
+  # ══════════════════════════════════════════════════════════════════════════
+  - key: operations-crm-handoff-pickup
+    name: Pick up handed-off clients
+    description: >-
+      Daily. Finds pod-wide clients the CRM marked ready or handed off that have
+      no engagement yet, and opens the delivery shell for them — a proposed
+      engagement plus a draft contract, both linked to the client. Deduped per
+      client, so it is safe to re-run.
+    triggerType: cron
+    triggerConfig:
+      expression: "0 7 * * *"
+    status: active
+    metadata:
+      templateKey: operations-crm-handoff-pickup
+      # Same pod-wide dependency as the briefing automation: `client` entities
+      # are pod-wide, and `scope: pod` is the explicit opt-in that must be
+      # DEPLOYED for this query to return anything.
+      requiresPodWideEntityQueryLens: true
+    flow:
+      nodes:
+        - id: trigger
+          type: trigger
+          position: { x: 0, y: 0 }
+          data:
+            label: Daily at 07:00
+            triggerType: cron
+            config:
+              expression: "0 7 * * *"
+
+        # READ-ONLY builtin. Enumerates parties carrying the pod-wide `client`
+        # ROLE. `scope: pod` is required — see the long note on the briefing
+        # automation's `list-clients` node.
+        - id: list-clients
+          type: capability
+          position: { x: 0, y: 120 }
+          data:
+            label: List clients (pod-wide `client` role)
+            verbId: entity.query
+            inputMapping:
+              profileSlug: client
+              scope: pod
+              limit: "100"
+
+        - id: handoff-loop
+          type: loop
+          position: { x: 0, y: 240 }
+          data:
+            label: For each client
+            iteratorExpression: steps.list-clients.output.entities
+            itemVariable: client
+
+        # READ-ONLY builtin. `handoffStatus` lives on the client FACET row, not
+        # on the entity — `entity.query`'s `filter` reads `entities.properties`
+        # and therefore cannot see it. This is the only door that returns facet
+        # overlay properties.
+        - id: read-client-facets
+          type: capability
+          position: { x: 0, y: 360 }
+          data:
+            label: Read this party's role facets
+            verbId: entity_facet.list
+            inputMapping:
+              entityId: "{{loop.item.id}}"
+
+        # Pull the CLIENT facet's handoffStatus out BY SLUG. Positional
+        # indexing (`facets.0.properties…`) would be a latent bug: facet order
+        # is not guaranteed, so on a party that is also a partner it would read
+        # the wrong row. `filter` + `map` resolves it by identity.
+        - id: client-handoff-status
+          type: transform
+          position: { x: 0, y: 480 }
+          data:
+            label: Read the client facet's handoff status
+            expression: "{{steps.read-client-facets.output.facets}} | filter:item.profileSlug === client | map:{{item.properties.handoffStatus}}"
+
+        # PER-ITEM FILTER (continue-semantics). `pending` means the CRM has not
+        # finished with this client yet — only ready/handed_off are ours.
+        - id: handoff-gate
+          type: condition
+          position: { x: 0, y: 600 }
+          data:
+            label: Only clients the CRM marked ready or handed off
+            expression: "steps.client-handoff-status.output.result contains-any ready,handed_off"
+
+        # Pure read, workspace-lensed (engagements are Operations-local, so no
+        # `scope: pod`). `engagement-client` is a real property def above, so
+        # this equality filter hits `entities.properties`.
+        #
+        # `filter` is authored as a JSON *STRING*, not a mapping, and that is
+        # load-bearing: `parseQueryFilterConditions` (automation-executor.ts)
+        # template-resolves the filter ONLY when it is a string. Written as a
+        # YAML object, `{{loop.item.id}}` would reach SQL as that literal text,
+        # match nothing, and this gate would then open for EVERY client.
+        - id: existing-engagements
+          type: query
+          position: { x: 0, y: 720 }
+          data:
+            label: Does this client already have an engagement?
+            profileSlug: engagement
+            filter: '{"engagement-client": "{{loop.item.id}}"}'
+            limit: 1
+
+        - id: engagement-gate
+          type: condition
+          position: { x: 0, y: 840 }
+          data:
+            label: Only clients with no engagement yet
+            expression: "steps.existing-engagements.output.count === 0"
+
+        # Cron trigger carries no payload timestamp, so `now` falls back to the
+        # actual run time — stamping the handoff moment onto both records
+        # below so they plot on the calendar the day they're handed off.
+        # `engagement-end`/`start`-adjacent dates the owner still sets by hand
+        # stay unset.
+        - id: handoff-time
+          type: compute
+          position: { x: 0, y: 900 }
+          data:
+            label: Record handoff time
+            operation: now
+
+        # GOVERNED WRITE via an `output` node. Created `proposed`, never active:
+        # the delivery shell exists so the work is visible, but a human decides
+        # when it starts. `dedupeBy: engagement-client` is the durable
+        # per-client idempotency key — a re-run SKIPS before the governance gate.
+        - id: create-engagement
+          type: output
+          position: { x: 0, y: 960 }
+          data:
+            label: Open a proposed engagement
+            outputType: entity_create
+            config:
+              profileSlug: engagement
+              title: "Engagement — {{loop.item.title}}"
+              dedupeBy: engagement-client
+              properties:
+                engagement-status: proposed
+                engagement-client: "{{loop.item.id}}"
+                engagement-start: "{{steps.handoff-time.output.result}}"
+                engagement-notes: "Opened automatically from the CRM handoff. Confirm scope, dates, and owner before activating."
+
+        - id: link-engagement
+          type: output
+          position: { x: 0, y: 1080 }
+          data:
+            label: Link engagement → client
+            outputType: relation_create
+            config:
+              fromEntityId: "{{steps.create-engagement.output.entityId}}"
+              toEntityId: "{{loop.item.id}}"
+              relationType: engagement_for_client
+
+        # Draft contract, deduped on the engagement it governs. A skipped
+        # (duplicate) engagement create still returns the existing entityId, so
+        # this stays correctly anchored on a partial re-run.
+        - id: create-contract
+          type: output
+          position: { x: 0, y: 1200 }
+          data:
+            label: Open a draft contract
+            outputType: entity_create
+            config:
+              profileSlug: contract
+              title: "Contract — {{loop.item.title}}"
+              dedupeBy: contract-engagement
+              properties:
+                contract-status: draft
+                contract-engagement: "{{steps.create-engagement.output.entityId}}"
+                start-date: "{{steps.handoff-time.output.result}}"
+                contract-notes: "Drafted automatically from the CRM handoff. Attach the signed document and set the term."
+
+        - id: link-contract
+          type: output
+          position: { x: 0, y: 1320 }
+          data:
+            label: Link contract → engagement
+            outputType: relation_create
+            config:
+              fromEntityId: "{{steps.create-contract.output.entityId}}"
+              toEntityId: "{{steps.create-engagement.output.entityId}}"
+              relationType: contract_for_engagement
+      edges:
+        - { id: h-trigger-list, source: trigger, target: list-clients }
+        # `handoff-time` is a `compute` node, and `compute` is NOT a per-item
+        # loop-body type — the executor's body walk STOPS at it. Sitting inside
+        # the loop chain it severed the body, orphaning create-engagement /
+        # link-engagement / create-contract / link-contract into the main pass
+        # where `{{loop.item.id}}` resolved to undefined (empty-id entities and
+        # relations). It is a RUN-level timestamp, identical for every item, so
+        # it belongs before the loop; `{{steps.handoff-time.output.result}}`
+        # still resolves from inside the body because step outputs are global.
+        - { id: h-list-time, source: list-clients, target: handoff-time }
+        - { id: h-time-loop, source: handoff-time, target: handoff-loop }
+        - { id: h-loop-facets, source: handoff-loop, target: read-client-facets }
+        - { id: h-facets-status, source: read-client-facets, target: client-handoff-status }
+        - { id: h-status-gate, source: client-handoff-status, target: handoff-gate }
+        - { id: h-gate-existing, source: handoff-gate, target: existing-engagements }
+        - { id: h-existing-gate, source: existing-engagements, target: engagement-gate }
+        - { id: h-gate-engagement, source: engagement-gate, target: create-engagement }
+        - { id: h-engagement-link, source: create-engagement, target: link-engagement }
+        - { id: h-link-contract, source: link-engagement, target: create-contract }
+        - { id: h-contract-link, source: create-contract, target: link-contract }

package/src/outreach-comms.yaml

@@ -203,6 +203,202 @@ playbooks:
       - entity.create
     status: active
 
+# ── LinkedIn conversation ingest (PURE-CONFIG automation — PROPOSAL) ─────────
+# Pulls LinkedIn threads via Unipile and records each as an EXTERNAL channel +
+# messages through the GENERIC `channel.ingest` verb. No provider code in the
+# pod — this composes existing verbs (unipile_list_accounts /
+# unipile_list_conversations / unipile_list_messages + channel.ingest).
+#
+# TRIGGER MODEL — ONE automation, both jobs (no high-freq polling):
+#   • RECONCILIATION: `triggerType: cron` at a LOW frequency (daily 06:00).
+#   • BACKFILL / on-demand: fire the SAME automation via
+#     `POST /automations/{id}/trigger` (MCP `synap_trigger_automation`), which
+#     "bypasses the automation's normal trigger config" and runs the flow once.
+# channel.ingest is idempotent, so cron sweeps and manual backfills are safe to
+# overlap and repeat.
+#
+# ⚠️ NEEDS-REVIEW — TWO verified engine constraints shape this flow; see the
+# handoff report. (1) The automation engine has NO nested loops
+# (LOOP_BODY_NODE_TYPES excludes `loop`/`sub_automation`), so the requested
+# `loop conversations → loop messages → channel.ingest per message` graph is
+# not expressible. This does ONE loop over conversations and hands each thread's
+# whole `messages` array to channel.ingest in a single call. (2) A `transform`
+# `map:` pipe can only project a single field/string per item, so it cannot
+# normalize messages into `{text, sentAt, participant, idempotencySeed}` objects
+# in-flow. => channel.ingest must accept a BATCH `messages: [...]` of raw
+# provider rows and do the per-message normalization + idempotent dedup
+# SERVER-SIDE. That is a contract change vs the single-message signature.
+# Kept `status: draft` until that batch shape ships; then activate.
+automations:
+  - key: linkedin-conversation-ingest
+    name: LinkedIn conversation ingest
+    description: >-
+      Pull LinkedIn conversations via Unipile and record each thread as an
+      external channel + its messages through channel.ingest (idempotent, so
+      re-runs are safe). Cron = low-frequency reconciliation; manual trigger =
+      on-demand backfill.
+    triggerType: cron
+    triggerConfig:
+      expression: "0 6 * * *"
+    status: draft
+    flow:
+      nodes:
+        - id: trigger
+          type: trigger
+          position: { x: 0, y: 0 }
+          data:
+            label: Daily 06:00 reconciliation (also fired manually for backfill)
+            triggerType: cron
+            config:
+              expression: "0 6 * * *"
+
+        # Resolve the connected account AT RUNTIME so the cron sweep needs no
+        # payload. A multi-account / multi-provider pod would still need a
+        # run-param accountId to sweep MORE than the first LinkedIn account — a
+        # per-account sweep would itself need the nested loop this engine lacks
+        # (secondary follow-up, noted in the report).
+        - id: list-accounts
+          type: capability
+          position: { x: 0, y: 120 }
+          data:
+            label: Resolve the connected Unipile account
+            verbId: unipile_list_accounts
+
+        # F5 — PROVIDER FILTER. `unipile_list_accounts` returns RAW Unipile v2
+        # account rows and a pod can connect several providers, so a non-LinkedIn
+        # account (WhatsApp / Telegram / Gmail) can sit at index 0. Taking a blind
+        # `accounts.0` would ingest that provider's threads AS linkedin. This
+        # `transform` node's array `filter:` pipe keeps ONLY LinkedIn accounts;
+        # every step below takes `.0` of the FILTERED list.
+        #   Field: the predicate matches the RAW Unipile v2 account shape
+        #   `type: 'LINKEDIN' | 'GMAIL' | 'WHATSAPP' | …` (verified in
+        #   UnipileConnector's UnipileAccountSchema, NOT the capability's loose
+        #   "provider" prose). evaluateCondition does an EXACT, case-sensitive
+        #   `==`, hence the uppercase literal.
+        #   Failure mode: if no LinkedIn account is connected (or the raw field
+        #   shape ever drifts) the filtered list is empty → the accountId below
+        #   resolves to "" → the run FAILS VISIBLY at list-conversations. It never
+        #   silently ingests the wrong provider — that is the point of F5.
+        #   Multi-LinkedIn-account: still takes the first; a run-param accountId
+        #   is the multi-account follow-up (noted in the report).
+        - id: filter-linkedin-account
+          type: transform
+          position: { x: 0, y: 180 }
+          data:
+            label: Keep only LinkedIn Unipile accounts
+            expression: "{{steps.list-accounts.output.accounts}} | filter:item.type == 'LINKEDIN'"
+
+        - id: list-conversations
+          type: capability
+          position: { x: 0, y: 240 }
+          data:
+            label: List LinkedIn conversations for the account
+            verbId: unipile_list_conversations
+            inputMapping:
+              accountId: "{{steps.filter-linkedin-account.output.result.0.id}}"
+
+        # NOTE: the automation engine caps loops at MAX_LOOP_ITERATIONS=100 per run
+        # (logs a warning, then truncates). So one cron pass reconciles the 100
+        # most-recent conversations; accounts with >100 threads need either a
+        # newest-first list (so the active threads are always covered) or a paged
+        # sweep (blocked today — would need the nested loops the engine lacks).
+        # Fine for the current dogfood scale; revisit if a user exceeds ~100 threads.
+        - id: conversations-loop
+          type: loop
+          position: { x: 0, y: 360 }
+          data:
+            label: For each conversation
+            iteratorExpression: steps.list-conversations.output.conversations
+            itemVariable: conversation
+
+        # Loop body (owned by conversations-loop): list this thread's messages,
+        # then ingest. `{{loop.item.id}}` is the chat/thread id for THIS
+        # iteration; `steps.list-messages` is re-bound per iteration.
+        - id: list-messages
+          type: capability
+          position: { x: 0, y: 480 }
+          data:
+            label: List this thread's messages
+            verbId: unipile_list_messages
+            inputMapping:
+              threadId: "{{loop.item.id}}"
+              accountId: "{{steps.filter-linkedin-account.output.result.0.id}}"
+
+        # GENERIC ingest — records the external channel for this thread and its
+        # messages, idempotently (dedup on a per-message idempotency seed derived
+        # SERVER-SIDE, e.g. `${externalId}:${sentAt}:${body}`). See the ⚠️ note:
+        # `messages` is a BATCH of raw provider rows (pending channel.ingest's
+        # batch contract).
+        - id: ingest
+          type: capability
+          position: { x: 0, y: 600 }
+          data:
+            label: Ingest thread + messages (idempotent, generic)
+            verbId: channel.ingest
+            inputMapping:
+              provider: linkedin
+              externalId: "{{loop.item.id}}"
+              title: "{{loop.item.name}}"
+              accountExternalId: "{{steps.filter-linkedin-account.output.result.0.id}}"
+              # F1 — TARGET THE CRM WORKSPACE. Without this, channel.ingest lands
+              # in the automation's OWN workspace, but the dashboard inbox reads
+              # "The arch CRM". Single-tenant target = the inbox/CRM workspace.
+              # TODO(multi-tenant): make this an install/run param instead of a
+              # literal (the flow schema has no template-var/param mechanism for a
+              # capability inputMapping today, so a documented literal is the
+              # single-tenant path — see the report).
+              workspaceId: "499328b7-fd35-4143-b1bc-67b9e45d9b4b"
+              # F2 — SUPPRESS THE BACKFILL STORM. This is a poll / reconciliation
+              # of HISTORICAL messages, so it must NOT emit
+              # `external_message.received` per message (channel resolve + dedup
+              # insert still run). Without this, one backfill of N threads fans
+              # out through the webhook + automation-trigger reactors N×messages.
+              suppressSideEffects: true
+              # BATCH mode: hand the whole thread's messages[] to the generic verb
+              # in ONE call (the engine has no nested loops). channel.ingest stays
+              # provider-agnostic — messageMap tells it (in CONFIG) where each field
+              # lives inside a raw Unipile v2 message row. Verified live 2026-07-27:
+              # a message = { id, text, timestamp (ISO), sender_id, is_sender, ... }.
+              messages: "{{steps.list-messages.output.messages}}"
+              messageMap:
+                text: text
+                id: id
+                sentAt: timestamp
+                # F3 — DIRECTION. `is_sender` (dot-path to a boolean per row) marks
+                # the operator's OWN sent messages as OUTBOUND so the inbox renders
+                # them right-aligned, instead of everything looking inbound.
+                isOutbound: is_sender
+                # F6 — participantExternalId DROPPED on purpose. link-at-birth
+                # binds the channel to the participant of the first-processed
+                # (newest) message, which — when that message is the account
+                # OWNER's own reply — mis-binds the whole thread to yourself. The
+                # channel `title` already carries the conversation (contact) name,
+                # so dropping the per-message sender id lets link-at-birth avoid
+                # the mis-bind.
+      edges:
+        - { id: e-trigger-accounts, source: trigger, target: list-accounts }
+        - {
+            id: e-accounts-filter,
+            source: list-accounts,
+            target: filter-linkedin-account,
+          }
+        - {
+            id: e-filter-convos,
+            source: filter-linkedin-account,
+            target: list-conversations,
+          }
+        - {
+            id: e-convos-loop,
+            source: list-conversations,
+            target: conversations-loop,
+          }
+        - {
+            id: e-loop-messages,
+            source: conversations-loop,
+            target: list-messages,
+          }
+        - { id: e-messages-ingest, source: list-messages, target: ingest }
+
 # LinkedIn send/search via Unipile, email send via Gmail (nango-google). The
 # user connects each once on install; a missing key fails gracefully per-skill.
 integrations:

package/src/project-management.yaml

@@ -268,7 +268,12 @@ profiles:
     icon: user
     color: "#0891B2"
     description: "Team member or stakeholder"
-    scope: WORKSPACE
+    # Pod-wide identity: `person` is ONE pod-wide SYSTEM kind. `entityScope: pod`
+    # lands the ROWS with `workspace_id = NULL` (visible from every workspace);
+    # `scope` omitted (no claim) so the applier reuses the system row and these
+    # project-management props land as this workspace's OVERLAY.
+    # (Was `scope: WORKSPACE`, which contradicted the pod-wide model.)
+    entityScope: pod
     properties:
       - slug: person-role
         label: Role