spine-framework 0.4.0 → 0.4.2

package/.env.example

@@ -69,8 +69,11 @@ APP_BASE_URL=http://localhost:8888
 # OPENAI_API_KEY=sk-...
 
 # ── Email (optional) ────────────────────────────────────────────
-# Provider: 'resend', 'sendgrid', or 'webhook' (default)
-# EMAIL_PROVIDER=resend
-# EMAIL_API_KEY=re_...
+# Resend API key for the 'transactional-email' integration (invites and
+# ticket-reply notifications). Until this is set, invites fall back to
+# copyable links and email notification stages skip silently.
+# RESEND_API_KEY=re_...
+# Sender identity for outbound email (e.g. 'Answer Once <noreply@yourdomain.com>').
+# Requires the domain to be verified in Resend; falls back to onboarding@resend.dev.
 # EMAIL_FROM=noreply@yourdomain.com
 # EMAIL_WEBHOOK_URL=https://hook.us1.make.com/your-scenario-id

package/.framework/cli/commands/install-app.ts

@@ -1377,24 +1377,28 @@ async function validatePipelineSeedStages(
       )
     }
 
-    if (stageType !== 'send_notification') continue
+    if (stageType !== 'send_notification' && stageType !== 'send_email') continue
     const recipients = stage.config?.recipients
     if (!Array.isArray(recipients)) {
-      throw new Error(`pipelines "${label}" (${file}) stage ${i} (send_notification): config.recipients must be an array`)
+      throw new Error(`pipelines "${label}" (${file}) stage ${i} (${stageType}): config.recipients must be an array`)
     }
     for (const recipient of recipients) {
       const roleMatch = typeof recipient === 'string' ? recipient.match(NOTIFICATION_ROLE_RE) : null
       if (roleMatch) {
         roleSlugs ??= await getRoleSlugs()
         if (!roleSlugs.has(roleMatch[1])) {
-          throw new Error(`pipelines "${label}" (${file}) stage ${i} (send_notification): recipient "${recipient}" references a role that does not exist`)
+          throw new Error(`pipelines "${label}" (${file}) stage ${i} (${stageType}): recipient "${recipient}" references a role that does not exist`)
         }
         continue
       }
-      if (recipient === 'self' || (typeof recipient === 'string' && NOTIFICATION_UUID_RE.test(recipient))) continue
+      if (
+        recipient === 'self' || recipient === 'owner' || recipient === 'watchers' ||
+        (typeof recipient === 'string' && NOTIFICATION_UUID_RE.test(recipient)) ||
+        (stageType === 'send_email' && typeof recipient === 'string' && recipient.includes('@'))
+      ) continue
       throw new Error(
-        `pipelines "${label}" (${file}) stage ${i} (send_notification): invalid recipient ${JSON.stringify(recipient)} — ` +
-        `expected 'role:<slug>', 'self', or a person UUID`
+        `pipelines "${label}" (${file}) stage ${i} (${stageType}): invalid recipient ${JSON.stringify(recipient)} — ` +
+        `expected 'role:<slug>', 'self', 'owner', 'watchers', a person UUID${stageType === 'send_email' ? ', or an email address' : ''}`
       )
     }
   }

package/.framework/functions/_shared/agent-runner.ts

@@ -4256,7 +4256,23 @@ export async function runAgent(
       const threadVisibility = thread?.visibility || 'external'
       let state = getResearchState(thread)
       if (userMessage?.trim()) {
-        await saveMessage(threadId, userMessage.trim(), 'human', null, ctx, replyTypeSlug, threadVisibility)
+        // Idempotent insert: the caller (ticket creation, sendMessage) often
+        // persists the inbound row itself. When the thread's latest inbound
+        // already carries this text the row exists — skip the insert so a
+        // re-fired kick/step can never double-post the question. New-turn
+        // semantics below (episode reset, user_question) are unaffected.
+        const { data: lastInboundRows } = await adminDb
+          .from('messages')
+          .select('content')
+          .eq('thread_id', threadId)
+          .eq('direction', 'inbound')
+          .order('sequence', { ascending: false })
+          .order('created_at', { ascending: false })
+          .limit(1)
+        const lastInbound = Array.isArray(lastInboundRows) ? lastInboundRows[0] : lastInboundRows
+        if ((lastInbound?.content || '').trim() !== userMessage.trim()) {
+          await saveMessage(threadId, userMessage.trim(), 'human', null, ctx, replyTypeSlug, threadVisibility)
+        }
         if (!state.user_question) state.user_question = userMessage.trim()
       }
       if (!userMessage?.trim() && !state.user_question) {

package/.framework/functions/_shared/pipeline-runner.ts

@@ -644,6 +644,64 @@ async function resolveAccountId(ctx: CoreContext, slug: string): Promise<string>
 // CIL[DOC-MICRO logic_summary="Template-bearing id fields resolve against config._triggerData then dynamic-import their engine — kb_ingest/kb_revoke import _shared/kb (canonical typed path with document lease); generate_embeddings/revoke_embeddings import functions/embeddings (legacy engine) and remain for cortex pipelines." notable_decisions="kb_ingest accepts item_id or document_id; kb_revoke accepts document_id or item_id — matching the seeded demo pipeline configs"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// Entity-scoped recipient handles understood by send_notification/send_email.
+// 'owner' = created_by of the record the trigger fired on (for a message, the
+// record its thread points at); 'watchers' = watchers rows on that record;
+// 'self' = the person who created the triggering record.
+const ENTITY_RECIPIENTS = new Set(['owner', 'watchers', 'self'])
+
+// Walks message -> thread -> target so entity handles resolve against the
+// owning record (e.g. the ticket item behind a reply), not just the event row.
+async function resolveEntityTarget(entity: any): Promise<{ targetTable: string | null, targetId: string | null }> {
+  if (!entity?.type || !entity?.id) return { targetTable: null, targetId: null }
+  if (entity.type === 'messages' && entity?.data?.thread_id) {
+    const { data: th } = await adminDb
+      .from('threads')
+      .select('target_type, target_id')
+      .eq('id', entity.data.thread_id)
+      .maybeSingle()
+    if (th?.target_id) {
+      return { targetTable: th.target_type || 'items', targetId: th.target_id }
+    }
+    return { targetTable: 'threads', targetId: entity.data.thread_id }
+  }
+  return { targetTable: entity.type, targetId: entity.id }
+}
+
+async function resolveEntityRecipients(recipients: any[], entity: any): Promise<string[]> {
+  const wanted = (recipients || []).filter((r: any) => ENTITY_RECIPIENTS.has(r))
+  if (!wanted.length) return []
+
+  const ids: string[] = []
+  if (wanted.includes('self') && entity?.data?.created_by) {
+    ids.push(entity.data.created_by)
+  }
+
+  if (wanted.includes('owner') || wanted.includes('watchers')) {
+    const { targetTable, targetId } = await resolveEntityTarget(entity)
+    if (targetTable && targetId) {
+      if (wanted.includes('owner')) {
+        const { data: rec } = await adminDb
+          .from(targetTable)
+          .select('created_by')
+          .eq('id', targetId)
+          .maybeSingle()
+        if (rec?.created_by) ids.push(rec.created_by)
+      }
+      if (wanted.includes('watchers')) {
+        const { data: ws } = await adminDb
+          .from('watchers')
+          .select('person_id')
+          .eq('target_id', targetId)
+        for (const w of ws || []) {
+          if (w?.person_id) ids.push(w.person_id)
+        }
+      }
+    }
+  }
+  return [...new Set(ids)]
+}
+
 const stageHandlers: Record<string, Function> = {
   'update_item': async (ctx: CoreContext, config: any) => {
     const triggerData = config._triggerData || {}
@@ -764,14 +822,46 @@ const stageHandlers: Record<string, Function> = {
   },
 
   'send_notification': async (ctx: CoreContext, config: any) => {
-    const { message, entity_type, entity_id, recipients = [] } = config
+    const triggerData = config._triggerData
+    const recipients = resolveTemplates(config.recipients ?? [], triggerData)
+    const entity = triggerData?.entity
+
+    // Entity-scoped handles ('owner', 'watchers', 'self') resolve through the
+    // record the trigger fired on; role:/UUID entries go through notify.ts.
+    const entityPersonIds = await resolveEntityRecipients(recipients, entity)
+    const personIds = [
+      ...entityPersonIds,
+      ...(await resolveNotificationRecipients(ctx, recipients.filter((r: any) => typeof r === 'string' && !ENTITY_RECIPIENTS.has(r))))
+    ]
+    const message = resolveTemplates(config.message, triggerData)
+    const entity_type = config.entity_type
+    // entity_id 'target' resolves the record behind the event (e.g. the ticket
+    // a reply was posted on) so notifications deep-link to it.
+    let entity_id = resolveTemplates(config.entity_id, triggerData)
+    if (entity_id === 'target') {
+      entity_id = (await resolveEntityTarget(entity)).targetId || null
+    }
 
     // watchers is the subscription table (who follows what) — deliveries go to
     // the notifications table, one row per recipient. Migration 050 adds it.
-    // CIL[DOC-NOTE type="behavior" content="Recipients may be person UUIDs or 'role:<slug>' handles — resolveNotificationRecipients maps role slugs to this account's active people ids; a role matching nobody is a valid 0-notification result, not an error."]
-    const personIds = await resolveNotificationRecipients(ctx, recipients)
-    const notifications = personIds.map((recipientId: string) => ({
-      account_id: ctx.accountId,
+    // Recipient account scoping: entity handles (owner/watchers/self) can point
+    // at people outside ctx.accountId — e.g. a staff reply in the support
+    // account notifying a customer — so each row is stamped with the
+    // recipient's own account_id, falling back to ctx.accountId.
+    // CIL[DOC-NOTE type="behavior" content="Recipients may be person UUIDs, 'role:<slug>' handles, or entity handles 'owner'/'watchers'/'self' — resolveNotificationRecipients maps role slugs to this account's active people ids; a role matching nobody is a valid 0-notification result, not an error."]
+    const uniquePersonIds = [...new Set(personIds)]
+    const personAccounts = new Map<string, string>()
+    if (uniquePersonIds.length) {
+      const { data: peopleRows } = await adminDb
+        .from('people')
+        .select('id, account_id')
+        .in('id', uniquePersonIds)
+      for (const p of peopleRows || []) {
+        if (p?.id && p?.account_id) personAccounts.set(p.id, p.account_id)
+      }
+    }
+    const notifications = uniquePersonIds.map((recipientId: string) => ({
+      account_id: personAccounts.get(recipientId) || ctx.accountId,
       person_id: recipientId,
       message,
       source_type: 'pipeline_execution',
@@ -792,6 +882,96 @@ const stageHandlers: Record<string, Function> = {
     return { success: true, notified_count: notifications.length }
   },
 
+  // Sends email through an outbound integration (e.g. Resend) to resolved
+  // recipients. Recipients accept literal emails plus the same handles as
+  // send_notification (role:<slug>, person UUID, 'owner', 'watchers', 'self').
+  // 'exclude_actor' (default true) drops the person who wrote the triggering
+  // record so a support rep never emails themselves. A missing/inactive
+  // integration is reported as success with emailed_count 0 — pipelines stay
+  // green until the customer configures a provider.
+  'send_email': async (ctx: CoreContext, config: any) => {
+    const triggerData = config._triggerData
+    const entity = triggerData?.entity
+    const integrationSlug = config.integration_slug || 'transactional-email'
+
+    const { data: integration } = await adminDb
+      .from('integrations')
+      .select('id, config')
+      .eq('slug', integrationSlug)
+      .eq('is_active', true)
+      .limit(1)
+      .maybeSingle()
+
+    // No configured provider → no-op so seeded pipelines stay green on installs
+    // that never set up email.
+    if (!integration) {
+      return { success: true, emailed_count: 0, skipped: 'integration not configured' }
+    }
+
+    // Named templates live on the integration (integration.config.templates.<key>
+    // = {subject, html, text}); inline stage config supplies them otherwise.
+    let { subject, html, text } = config
+    const named = config.template && integration?.config?.templates?.[config.template]
+    if (named) {
+      subject = named.subject ?? subject
+      html = named.html ?? html
+      text = named.text ?? text
+    }
+    subject = resolveTemplates(subject, triggerData)
+    html = resolveTemplates(html, triggerData)
+    text = resolveTemplates(text, triggerData)
+
+    if (!subject || (!html && !text)) {
+      throw new Error('send_email: subject and html or text are required (inline or via integration template)')
+    }
+
+    const recipients = resolveTemplates(config.recipients ?? [], triggerData)
+    const personIds = new Set([
+      ...(await resolveEntityRecipients(recipients, entity)),
+      ...(await resolveNotificationRecipients(ctx, recipients.filter((r: any) => typeof r === 'string' && !ENTITY_RECIPIENTS.has(r) && !r.includes('@')))),
+    ])
+    if (config.exclude_actor !== false && entity?.data?.created_by) {
+      personIds.delete(entity.data.created_by)
+    }
+
+    const emails = new Set(recipients.filter((r: any) => typeof r === 'string' && r.includes('@')))
+    if (personIds.size) {
+      const { data: people } = await adminDb
+        .from('people')
+        .select('id, email')
+        .in('id', [...personIds])
+      for (const p of people || []) {
+        if (p?.email) emails.add(p.email)
+      }
+    }
+
+    if (!emails.size) return { success: true, emailed_count: 0 }
+
+    try {
+      const result = await executeOutbound(ctx, {
+        integration_slug: integrationSlug,
+        action_config: {
+          action_slug: 'send_email',
+          to: [...emails],
+          subject,
+          html,
+          text,
+          ...(config.from ? { from: config.from } : {}),
+          ...(config.reply_to ? { reply_to: config.reply_to } : {}),
+        },
+      })
+      return { success: !!result?.success, emailed_count: emails.size }
+    } catch (err: any) {
+      // Credential/env problems mean the provider was never configured — treat
+      // like "not configured" rather than failing the pipeline.
+      if (/credential|Environment variable|api_token/i.test(err?.message || '')) {
+        console.warn(`[send_email] skipped — ${err.message}`)
+        return { success: true, emailed_count: 0, skipped: err.message }
+      }
+      throw err
+    }
+  },
+
   'run_pipeline': async (ctx: CoreContext, config: any) => {
     const { pipeline_id, trigger_data = {} } = config
     

package/.framework/functions/adapters/resend-outbound.ts

@@ -0,0 +1,44 @@
+// Resend outbound adapter — maps a composed email in actionConfig to the
+// Resend /emails API. `from` resolves actionConfig.from -> integration.config.from
+// -> EMAIL_FROM env -> Resend's shared onboarding sender, so a fresh install
+// delivers test mail before the customer verifies their own domain.
+
+export function buildRequest(_record: any, ctx: any) {
+  const apiKey = ctx?.apiKey?.value
+  const a = ctx?.actionConfig || {}
+  const to = Array.isArray(a.to) ? a.to : a.to ? [a.to] : []
+
+  if (!to.length) {
+    throw new Error('resend-outbound adapter requires actionConfig.to')
+  }
+  if (!a.subject) {
+    throw new Error('resend-outbound adapter requires actionConfig.subject')
+  }
+  if (!apiKey) {
+    throw new Error('resend-outbound adapter requires api_token credential')
+  }
+
+  const from =
+    a.from ||
+    ctx?.integration?.config?.from ||
+    process.env.EMAIL_FROM ||
+    'onboarding@resend.dev'
+
+  const body: Record<string, any> = {
+    from,
+    to,
+    subject: a.subject,
+    ...(a.html ? { html: a.html } : { text: a.text || '' }),
+  }
+  if (a.reply_to) body.reply_to = a.reply_to
+
+  return {
+    url: ctx?.integration?.config?.api_url || 'https://api.resend.com/emails',
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body,
+  }
+}

package/.framework/functions/integration-outbound.ts

@@ -15,6 +15,7 @@ import { resolveCredential } from './_shared/resolve-credentials'
 import { get as adminDataGet, update as adminDataUpdate } from './admin-data'
 import * as openaiOutbound from './adapters/openai-outbound'
 import * as genericWebhookOutbound from './adapters/generic-webhook-outbound'
+import * as resendOutbound from './adapters/resend-outbound'
 // CIL[DOC-VECTOR type="context" content="purpose='Module header: imports and adapter registration for outbound integration delivery'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
@@ -368,7 +369,8 @@ export async function execute(ctx: CoreContext, body: any = {}): Promise<any> {
 // CIL[DOC-STABILITY stability="stable"]
 const builtInOutboundAdapters: Record<string, any> = {
   'adapters/openai-outbound': openaiOutbound,
-  'adapters/generic-webhook-outbound': genericWebhookOutbound
+  'adapters/generic-webhook-outbound': genericWebhookOutbound,
+  'adapters/resend-outbound': resendOutbound
 }
 // CIL[DOC-VECTOR type="context" content="purpose='Registry of built-in outbound adapter modules'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]

package/.framework/functions/invites.ts

@@ -821,17 +821,21 @@ export const createInvite = createHandler(async (ctx, body) => {
   const appBaseUrl = resolveInviteBaseUrl(base_url)
   const inviteUrl = `${appBaseUrl}/register?t=${token}`
 
-  // Email delivery: when an 'invite-email' integration is configured, send the
-  // invite through the outbound broker. Always return invite_url so the UI can
-  // fall back to a copyable link when no provider is configured.
+  // Email delivery: when an 'invite-email' integration (or the shared
+  // 'transactional-email' one) is configured, send the invite through the
+  // outbound broker. Always return invite_url so the UI can fall back to a
+  // copyable link when no provider is configured.
   let emailSent = false
   try {
-    const { data: emailIntegration } = await adminDb
+    const { data: emailIntegrations } = await adminDb
       .from('integrations')
-      .select('id')
-      .eq('slug', 'invite-email')
+      .select('id, slug, config')
+      .in('slug', ['invite-email', 'transactional-email'])
       .eq('is_active', true)
-      .maybeSingle()
+
+    const emailIntegration =
+      (emailIntegrations || []).find((i: any) => i.slug === 'invite-email') ||
+      (emailIntegrations || [])[0]
 
     if (emailIntegration) {
       const { data: account } = await adminDb
@@ -839,14 +843,36 @@ export const createInvite = createHandler(async (ctx, body) => {
         .select('display_name')
         .eq('id', account_id)
         .maybeSingle()
+      const accountName = account?.display_name || ''
+
+      // Email body: integration.config.templates.invite overrides the default.
+      // Template placeholders are {{to_name}}, {{invite_url}}, {{account_name}},
+      // {{expires_at}}.
+      const tpl = emailIntegration.config?.templates?.invite || {}
+      const render = (s: string) =>
+        (s || '')
+          .replace(/\{\{\s*to_name\s*\}\}/g, stubName || '')
+          .replace(/\{\{\s*invite_url\s*\}\}/g, inviteUrl)
+          .replace(/\{\{\s*account_name\s*\}\}/g, accountName)
+          .replace(/\{\{\s*expires_at\s*\}\}/g, expiresAt || '')
+      const subject = render(tpl.subject) ||
+        `You're invited to join ${accountName || 'your team'}`
+      const html = render(tpl.html) ||
+        `<p>Hi${stubName ? ' ' + stubName : ''},</p>` +
+        `<p>You've been invited to join <strong>${accountName || 'the team'}</strong>.</p>` +
+        `<p><a href="${inviteUrl}">Accept your invitation</a></p>` +
+        `<p>This link expires ${expiresAt || 'soon'}. If the button doesn't work, paste this into your browser:<br>${inviteUrl}</p>`
+
       await checkRateLimit(ctx, 'invite_email', { identifier: `acct:${account_id}` })
       const result = await executeOutbound(ctx, {
-        integration_slug: 'invite-email',
+        integration_slug: emailIntegration.slug,
         action_config: {
           to: email,
-          to_name: stubName,
+          subject,
+          html,
           invite_url: inviteUrl,
-          account_name: account?.display_name || '',
+          to_name: stubName,
+          account_name: accountName,
           invited_by: ctx.principal.id,
           expires_at: expiresAt,
         }

package/.framework/migrations/062_send_email_action.sql

@@ -0,0 +1,9 @@
+-- Seeds the send_email pipeline action. send_email resolves recipients
+-- (literal emails, person UUIDs, 'role:<slug>', or entity handles
+-- 'owner'/'watchers'/'self') and sends through an outbound integration
+-- (default slug 'transactional-email', e.g. Resend). No-op when the
+-- integration is not configured.
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'send_email', 'Send Email', 'Core pipeline stage: send email to resolved recipients via an outbound email integration.', 'send_email', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'send_email');

package/.framework/tests/unit/pipeline-runner.test.ts

@@ -16,7 +16,8 @@ vi.mock('../../functions/_shared/db.ts', () => ({
 
 vi.mock('../../functions/_shared/audit.ts', () => ({
   emitAudit: vi.fn().mockResolvedValue(undefined),
-  emitSpan: vi.fn().mockResolvedValue(undefined)
+  emitSpan: vi.fn().mockResolvedValue(undefined),
+  emitLog: vi.fn().mockResolvedValue(undefined)
 }))
 
 vi.mock('../../functions/embeddings.ts', () => ({
@@ -610,7 +611,7 @@ describe('send_notification — writes to notifications, not watchers', () => {
           insert: vi.fn(() => Promise.resolve({ data: null, error: { message: 'watchers must not receive notification payloads' } }))
         } as any
       }
-      return { select: vi.fn().mockReturnThis(), eq: vi.fn().mockReturnThis(), insert: vi.fn().mockReturnThis(), update: vi.fn().mockReturnThis(), single: vi.fn().mockResolvedValue({ data: null, error: null }) } as any
+      return { select: vi.fn().mockReturnThis(), eq: vi.fn().mockReturnThis(), in: vi.fn().mockReturnThis(), is: vi.fn().mockReturnThis(), not: vi.fn().mockReturnThis(), limit: vi.fn().mockReturnThis(), order: vi.fn().mockReturnThis(), maybeSingle: vi.fn().mockResolvedValue({ data: null, error: null }), insert: vi.fn().mockReturnThis(), update: vi.fn().mockReturnThis(), single: vi.fn().mockResolvedValue({ data: null, error: null }) } as any
     })
   }
 
@@ -666,6 +667,10 @@ describe('send_notification — role:<slug> recipient resolution', () => {
     const peopleQ: any = {
       select: vi.fn(() => peopleQ),
       eq: vi.fn(() => peopleQ),
+      in: vi.fn(() => peopleQ),
+      is: vi.fn(() => peopleQ),
+      limit: vi.fn(() => peopleQ),
+      maybeSingle: vi.fn(() => Promise.resolve({ data: null, error: null })),
       then: (onF: any, onR: any) =>
         Promise.resolve({ data: peopleRows, error: peopleError ?? null }).then(onF, onR)
     }
@@ -708,7 +713,7 @@ describe('send_notification — role:<slug> recipient resolution', () => {
           })
         } as any
       }
-      return { select: vi.fn().mockReturnThis(), eq: vi.fn().mockReturnThis(), insert: vi.fn().mockReturnThis(), update: vi.fn().mockReturnThis(), single: vi.fn().mockResolvedValue({ data: null, error: null }) } as any
+      return { select: vi.fn().mockReturnThis(), eq: vi.fn().mockReturnThis(), in: vi.fn().mockReturnThis(), is: vi.fn().mockReturnThis(), not: vi.fn().mockReturnThis(), limit: vi.fn().mockReturnThis(), order: vi.fn().mockReturnThis(), maybeSingle: vi.fn().mockResolvedValue({ data: null, error: null }), insert: vi.fn().mockReturnThis(), update: vi.fn().mockReturnThis(), single: vi.fn().mockResolvedValue({ data: null, error: null }) } as any
     })
   }
 
@@ -752,4 +757,166 @@ describe('send_notification — role:<slug> recipient resolution', () => {
     }
   })
 })
-// CIL[END stable_id="~/.framework/tests/unit/pipeline-runner.test.ts:describe_sendNotification_roleRecipients:block"]
+// CIL[END stable_id="~/.framework/tests/unit/pipeline-runner.test.ts:describe_sendNotification_roleRecipients:block"]
+// send_email — resolves entity recipients through message->thread->target,
+// composes from integration templates or inline config, and skips cleanly when
+// no provider is configured.
+describe('send_email — recipient resolution + outbound send', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  const OWNER_ID = '33333333-3333-4333-8333-333333333333'
+  const ACTOR_ID = '44444444-4444-4444-8444-444444444444'
+  const triggerData = {
+    entity: {
+      type: 'messages',
+      id: 'm-1',
+      data: { thread_id: 'th-1', created_by: ACTOR_ID, content: 'reply body', direction: 'outbound', visibility: 'external' },
+    },
+  }
+
+  function mockEmailPipeline(stageConfig: any, integrationRow: any) {
+    const chain: any = {
+      select: vi.fn(() => chain),
+      eq: vi.fn(() => chain),
+      in: vi.fn(() => chain),
+      is: vi.fn(() => chain),
+      not: vi.fn(() => chain),
+      limit: vi.fn(() => chain),
+      order: vi.fn(() => chain),
+      insert: vi.fn(() => chain),
+      update: vi.fn(() => chain),
+      single: vi.fn(() => Promise.resolve({ data: null, error: null })),
+      maybeSingle: vi.fn(() => Promise.resolve({ data: null, error: null })),
+      then: (onF: any, onR: any) => Promise.resolve({ data: null, error: null }).then(onF, onR),
+    }
+    vi.mocked(adminDb.from).mockImplementation((table: string) => {
+      if (table === 'pipelines') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          single: vi.fn().mockResolvedValue({
+            data: { id: 'pipe-1', stages: [{ stage_type: 'send_email', config: stageConfig }], is_active: true },
+            error: null,
+          }),
+        } as any
+      }
+      if (table === 'pipeline_executions') {
+        return {
+          insert: vi.fn().mockReturnThis(),
+          update: vi.fn().mockReturnThis(),
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockResolvedValue({ data: null, error: null }),
+          single: vi.fn().mockResolvedValue({ data: { id: EXEC_ID }, error: null }),
+        } as any
+      }
+      if (table === 'actions') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          single: vi.fn().mockResolvedValue({
+            data: { id: 'a-2', handler: 'send_email', handler_module: 'functions', config: {} },
+            error: null,
+          }),
+        } as any
+      }
+      if (table === 'integrations') {
+        const q: any = {
+          select: vi.fn(() => q), eq: vi.fn(() => q), in: vi.fn(() => q), is: vi.fn(() => q),
+          limit: vi.fn(() => q),
+          single: vi.fn(() => Promise.resolve({ data: integrationRow, error: null })),
+          maybeSingle: vi.fn(() => Promise.resolve({ data: integrationRow, error: null })),
+        }
+        return q
+      }
+      if (table === 'threads') {
+        const q: any = {
+          select: vi.fn(() => q), eq: vi.fn(() => q),
+          maybeSingle: vi.fn(() => Promise.resolve({ data: { target_type: 'items', target_id: 'item-1' }, error: null })),
+        }
+        return q
+      }
+      if (table === 'items') {
+        const q: any = {
+          select: vi.fn(() => q), eq: vi.fn(() => q),
+          maybeSingle: vi.fn(() => Promise.resolve({ data: { created_by: OWNER_ID }, error: null })),
+        }
+        return q
+      }
+      if (table === 'people') {
+        const ALL_PEOPLE = [
+          { id: OWNER_ID, email: 'owner@x.test', account_id: 'acct-cust' },
+          { id: ACTOR_ID, email: 'staff@x.test', account_id: 'acct-staff' },
+        ]
+        let idsFilter: string[] | null = null
+        const q: any = {
+          select: vi.fn(() => q), eq: vi.fn(() => q),
+          in: vi.fn((_col: string, ids: string[]) => { idsFilter = ids; return q }),
+          then: (onF: any, onR: any) =>
+            Promise.resolve({ data: ALL_PEOPLE.filter(p => !idsFilter || idsFilter.includes(p.id)), error: null }).then(onF, onR),
+        }
+        return q
+      }
+      if (table === 'webhook_deliveries') {
+        const q: any = {
+          select: vi.fn(() => q), eq: vi.fn(() => q), in: vi.fn(() => q),
+          insert: vi.fn(() => q), update: vi.fn(() => q),
+          single: vi.fn(() => Promise.resolve({ data: { id: 'del-1' }, error: null })),
+          maybeSingle: vi.fn(() => Promise.resolve({ data: null, error: null })),
+          then: (onF: any, onR: any) => Promise.resolve({ data: null, error: null }).then(onF, onR),
+        }
+        return q
+      }
+      return chain
+    })
+  }
+
+  const resendIntegration = {
+    id: 'int-1',
+    slug: 'transactional-email',
+    config: {
+      outbound_adapter: 'adapters/resend-outbound',
+      api_url: 'https://api.resend.com/emails',
+      from: 'Support <noreply@x.test>',
+      templates: { ticket_reply: { subject: 'Re: ticket', text: 'staff said: {{record.content}}' } },
+    },
+    credentials: { api_token: { source: 'value', value: 're_test' } },
+  }
+
+  it("emails the ticket owner via Resend and excludes the actor", async () => {
+    mockEmailPipeline(
+      { integration_slug: 'transactional-email', template: 'ticket_reply', recipients: ['owner'], exclude_actor: true },
+      resendIntegration
+    )
+    const fetchSpy = vi.fn().mockResolvedValue(new Response('{"id":"em_1"}', { status: 200 }))
+    vi.stubGlobal('fetch', fetchSpy)
+
+    const result = await runPipeline('pipe-1', triggerData, makeCtx())
+    expect(result.stages[0].status).toBe('success')
+    expect(result.stages[0].output.emailed_count).toBe(1)
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchSpy.mock.calls[0]
+    expect(url).toBe('https://api.resend.com/emails')
+    const body = JSON.parse(init.body)
+    expect(body.to).toEqual(['owner@x.test'])           // owner resolved through message->thread->item
+    expect(body.to).not.toContain('staff@x.test')       // actor excluded
+    expect(body.from).toBe('Support <noreply@x.test>')
+    expect(body.subject).toBe('Re: ticket')
+    expect(init.headers.Authorization).toBe('Bearer re_test')
+    vi.unstubAllGlobals()
+  })
+
+  it('no-ops with emailed_count 0 when the integration is not configured', async () => {
+    mockEmailPipeline(
+      { integration_slug: 'transactional-email', subject: 'x', text: 'y', recipients: ['owner'] },
+      null
+    )
+    const result = await runPipeline('pipe-1', triggerData, makeCtx())
+    expect(result.stages[0].status).toBe('success')
+    expect(result.stages[0].output.emailed_count).toBe(0)
+    expect(result.stages[0].output.skipped).toMatch(/not configured/)
+  })
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {