@fleox-agent-crm/agentcrm 0.0.0-stage → 0.3.1

package/dist/agent/chunks/automations-DwWruxmu.mjs

@@ -0,0 +1,698 @@
+import { createRequire as __acrmRequire } from "node:module";
+import { fileURLToPath as __acrmPath } from "node:url";
+import { dirname as __acrmDirname } from "node:path";
+const require2 = __acrmRequire(import.meta.url);
+const __filename = __acrmPath(import.meta.url);
+const __dirname = __acrmDirname(__filename);
+import { toIsoDate, recordLabel, formatFieldValue, normalizeEmail } from "./fields-B0bitgmr.mjs";
+import { n as newId } from "./ids-CvnmrMJX.mjs";
+import { plugins } from "./pluginRegistry-DyHtlkcr.mjs";
+import { r as resolveField, m as matchesFilter } from "./query-C5nJB_3C.mjs";
+import { queryContext, setRecordOwner, updateRecord } from "./records-DcHFelq5.mjs";
+import { getSettings } from "./settings-Di8nzNEL.mjs";
+import { userOf, automationRunsOf, asDoc, requireRecord, requireObject, automationsOf, objectOf, recordsOf, thaw, recordOf, usersOf } from "./store-5gqRSKXg.mjs";
+import { F as FILTER_OPS } from "../agentcrm.mjs";
+import { lastActivityAt, addNote, createTask } from "./activities-Cj_SIOay.mjs";
+import { OpsError, assertCan } from "./context-CxFfqS4D.mjs";
+import { pipelineOfRecord } from "./pipelines-BAKpPk1w.mjs";
+import { getAutomationAction, listAutomationActions } from "./extensionActions-D2HtpQz4.mjs";
+import { registerAutomationAction, subscribeAutomationActions } from "./extensionActions-D2HtpQz4.mjs";
+import "./standardObjects-CheqfDqa.mjs";
+import "./relations-B9TynBmA.mjs";
+import "./runtimeConfig-CCOFg1RM.mjs";
+import "node:util";
+import "node:fs";
+import "node:path";
+import "node:url";
+import "node:crypto";
+import "node:os";
+import "node:child_process";
+import "node:http";
+const AUTOMATION_TEMPLATES = [
+  {
+    id: "deal-won-onboarding",
+    name: "Deal won → onboarding task",
+    description: "When a deal reaches a won stage, create an onboarding task for its owner due in 2 days and log a note.",
+    requires: ["deals"],
+    build: () => ({
+      name: "Deal won → onboarding task",
+      object: "deals",
+      trigger: { type: "stage.changed", to: "won" },
+      conditions: [],
+      actions: [
+        { type: "createTask", title: "Kick off onboarding for {{label}}", dueInDays: 2, assignTo: "owner" },
+        { type: "addNote", body: "🎉 Deal won ({{amount}}). Onboarding task created for {{owner}}." }
+      ]
+    })
+  },
+  {
+    id: "new-lead-round-robin",
+    name: "New lead → assign round robin",
+    description: "When a person is created as a lead, assign an owner in turn among active admins and members, and create a first-touch task.",
+    requires: ["people"],
+    build: () => ({
+      name: "New lead → assign round robin",
+      object: "people",
+      trigger: { type: "record.created" },
+      conditions: [{ field: "lifecycleStage", op: "eq", value: "lead" }],
+      actions: [
+        { type: "assignOwner", userId: "roundRobin" },
+        { type: "createTask", title: "First touch: {{label}}", dueInDays: 1, assignTo: "owner" }
+      ]
+    })
+  },
+  {
+    id: "stale-deal-followup",
+    name: "Deal stale 14 days → follow-up task",
+    description: "Every check, open deals without any activity for 14 days get a follow-up task for their owner (once per idle period).",
+    requires: ["deals"],
+    build: () => ({
+      name: "Deal stale 14 days → follow-up task",
+      object: "deals",
+      trigger: { type: "inactivity", days: 14 },
+      conditions: [{ field: "stage", op: "notIn", value: ["won", "lost"] }],
+      actions: [{ type: "createTask", title: "Follow up on {{label}} (no activity for 14 days)", dueInDays: 1, assignTo: "owner" }]
+    })
+  },
+  {
+    id: "deal-lost-note",
+    name: "Deal lost → log the reason",
+    description: "When a deal moves to a lost stage, log a note with the lost reason on its timeline.",
+    requires: ["deals"],
+    build: () => ({
+      name: "Deal lost → log the reason",
+      object: "deals",
+      trigger: { type: "stage.changed", to: "lost" },
+      conditions: [],
+      actions: [{ type: "addNote", body: "Deal lost. Reason: {{lostReason}}" }]
+    })
+  },
+  {
+    id: "customer-welcome",
+    name: "New customer → welcome task",
+    description: "When a person's lifecycle stage becomes Customer, create a task to send the welcome pack.",
+    requires: ["people"],
+    build: () => ({
+      name: "New customer → welcome task",
+      object: "people",
+      trigger: { type: "field.changed", field: "lifecycleStage", to: "customer" },
+      conditions: [],
+      actions: [{ type: "createTask", title: "Send the welcome pack to {{label}}", dueInDays: 3, assignTo: "owner" }]
+    })
+  },
+  {
+    id: "new-person-webhook",
+    name: "New person → webhook",
+    description: "POST every new person as JSON to a URL you own (Zapier, Make, n8n, Slack workflow…). Set the URL before enabling.",
+    requires: ["people"],
+    build: () => ({
+      name: "New person → webhook",
+      enabled: false,
+      object: "people",
+      trigger: { type: "record.created" },
+      conditions: [],
+      actions: [{ type: "webhook", url: "https://example.com/your-webhook" }]
+    })
+  }
+];
+function findAutomationTemplate(id) {
+  return AUTOMATION_TEMPLATES.find((t) => t.id === id);
+}
+const PLACEHOLDER = /\{\{\s*([\w.-]+)\s*\}\}/g;
+function templatePlaceholders(template) {
+  return [...template.matchAll(PLACEHOLDER)].map((m) => m[1]);
+}
+function renderTemplate(ctx, template, record, object) {
+  if (!template.includes("{{")) return template;
+  let locale;
+  let currency;
+  try {
+    const s = getSettings({ ...ctx, user: null });
+    locale = s.locale;
+    currency = s.defaultCurrency;
+  } catch {
+  }
+  const fmt = object ? { ...queryContext(ctx, object), locale, currency } : { locale, currency };
+  return template.replace(PLACEHOLDER, (_m, key) => {
+    switch (key) {
+      case "label":
+      case "recordLabel":
+        return recordLabel(object, record);
+      case "object":
+        return object?.labelSingular ?? record.object;
+      case "id":
+        return record.id;
+      case "today":
+        return toIsoDate(new Date(ctx.now()));
+      case "owner":
+        return record.ownerId ? userOf(ctx.store, record.ownerId)?.name ?? "" : "";
+      case "owner.email":
+        return record.ownerId ? userOf(ctx.store, record.ownerId)?.email ?? "" : "";
+      case "owner.id":
+        return record.ownerId ?? "";
+    }
+    const field = object ? resolveField(object, key) : void 0;
+    const value = key in record.fields ? record.fields[key] : record[key];
+    if (value === void 0 || value === null) return "";
+    if (!field) return typeof value === "object" ? JSON.stringify(value) : String(value);
+    return formatFieldValue(field, value, fmt);
+  });
+}
+function summarizeForWebhook(ctx, record, object) {
+  const qctx = queryContext(ctx, object);
+  const display = {};
+  for (const field of object.fields) {
+    const v = record.fields[field.id];
+    if (v === void 0 || v === null) continue;
+    display[field.id] = formatFieldValue(field, v, qctx);
+  }
+  const owner = record.ownerId ? userOf(ctx.store, record.ownerId) : void 0;
+  return {
+    id: record.id,
+    object: record.object,
+    label: recordLabel(object, record),
+    fields: record.fields,
+    display,
+    ...owner ? { owner: { id: owner.id, name: owner.name, email: owner.email } } : {},
+    createdAt: new Date(record.createdAt).toISOString(),
+    updatedAt: new Date(record.updatedAt).toISOString()
+  };
+}
+const MAX_AUTOMATION_DEPTH = 3;
+const MAX_AUTOMATION_RUNS = 1e3;
+const DAY = 864e5;
+const HOUR = 36e5;
+const EVENT_TRIGGERS = ["record.created", "record.updated", "field.changed", "stage.changed"];
+const SCHEDULED_TRIGGERS = ["schedule", "inactivity"];
+const TRIGGER_TYPES = [...EVENT_TRIGGERS, ...SCHEDULED_TRIGGERS];
+const ACTION_TYPES = ["createTask", "updateField", "addNote", "assignOwner", "webhook", "extension"];
+let webhookFetch = null;
+function setAutomationFetch(fn) {
+  webhookFetch = fn;
+}
+function listAutomations(ctx) {
+  return ctx.store.list("automations");
+}
+function getAutomation(ctx, id) {
+  const a = ctx.store.get("automations", id);
+  if (!a) throw new OpsError("notFound", `Automation "${id}" not found.`);
+  return a;
+}
+function listAutomationRuns(ctx, opts = {}) {
+  let runs = automationRunsOf(ctx.store);
+  if (opts.automationId) runs = runs.filter((r) => r.automationId === opts.automationId);
+  if (opts.recordId) runs = runs.filter((r) => r.recordId === opts.recordId);
+  if (opts.status) runs = runs.filter((r) => r.status === opts.status);
+  runs = [...runs].sort((a, b) => b.startedAt - a.startedAt || (a.id < b.id ? 1 : -1));
+  return opts.limit ? runs.slice(0, opts.limit) : runs;
+}
+function fieldExists(object, id) {
+  return !!resolveField(object, id);
+}
+function validateAutomation(ctx, input) {
+  const errors = [];
+  const name = (input.name ?? "").trim();
+  if (!name) errors.push("A name is required.");
+  const object = objectOf(ctx.store, input.object);
+  if (!object) errors.push(`Unknown object "${input.object}".`);
+  const trigger = { ...input.trigger ?? { type: "record.created" } };
+  if (!TRIGGER_TYPES.includes(trigger.type)) errors.push(`Unknown trigger "${String(trigger.type)}". Triggers: ${TRIGGER_TYPES.join(", ")}.`);
+  if (trigger.type === "field.changed" && !trigger.field) errors.push("A field.changed trigger needs a field.");
+  if (trigger.field && object && !fieldExists(object, trigger.field)) errors.push(`Trigger field "${trigger.field}" doesn't exist on ${object.labelPlural}.`);
+  if (trigger.type === "inactivity" && !(typeof trigger.days === "number" && trigger.days >= 1)) errors.push("An inactivity trigger needs days ≥ 1.");
+  if (trigger.type === "schedule" && !(typeof trigger.everyHours === "number" && trigger.everyHours >= 1)) errors.push("A schedule trigger needs everyHours ≥ 1.");
+  if (trigger.type === "stage.changed" && object && !ctx.store.list("pipelines").some((p) => p.object === object.id)) errors.push(`${object.labelPlural} have no pipeline.`);
+  const conditions = [];
+  for (const c of input.conditions ?? []) {
+    if (!c || typeof c.field !== "string") {
+      errors.push("Invalid condition.");
+      continue;
+    }
+    if (!FILTER_OPS.includes(c.op)) errors.push(`Unknown condition operator "${String(c.op)}".`);
+    if (object && !fieldExists(object, c.field)) errors.push(`Condition field "${c.field}" doesn't exist on ${object.labelPlural}.`);
+    conditions.push({ field: c.field, op: c.op, ...c.value !== void 0 ? { value: c.value } : {} });
+  }
+  const actions = [];
+  if (!input.actions?.length) errors.push("Add at least one action.");
+  for (const [i, a] of (input.actions ?? []).entries()) {
+    const n = `Action ${i + 1}`;
+    switch (a?.type) {
+      case "createTask":
+        if (!a.title?.trim()) errors.push(`${n}: a task title is required.`);
+        if (a.dueInDays !== void 0 && !(typeof a.dueInDays === "number" && a.dueInDays >= 0)) errors.push(`${n}: dueInDays must be ≥ 0.`);
+        if (a.assignTo && a.assignTo !== "owner" && !userOf(ctx.store, a.assignTo)) errors.push(`${n}: unknown user "${a.assignTo}".`);
+        actions.push({ type: "createTask", title: a.title?.trim() ?? "", ...a.dueInDays !== void 0 ? { dueInDays: a.dueInDays } : {}, ...a.assignTo ? { assignTo: a.assignTo } : {} });
+        break;
+      case "updateField":
+        if (!a.field) errors.push(`${n}: pick a field.`);
+        else if (object && !object.fields.some((f) => f.id === a.field)) errors.push(`${n}: field "${a.field}" doesn't exist on ${object.labelPlural}.`);
+        actions.push({ type: "updateField", field: a.field, value: a.value });
+        break;
+      case "addNote":
+        if (!a.body?.trim()) errors.push(`${n}: the note is empty.`);
+        actions.push({ type: "addNote", body: a.body ?? "" });
+        break;
+      case "assignOwner":
+        if (!a.userId) errors.push(`${n}: pick a user or round robin.`);
+        else if (a.userId !== "roundRobin" && !userOf(ctx.store, a.userId)) errors.push(`${n}: unknown user "${a.userId}".`);
+        actions.push({ type: "assignOwner", userId: a.userId });
+        break;
+      case "webhook":
+        if (!/^https?:\/\/\S+$/i.test(a.url ?? "")) errors.push(`${n}: the webhook URL must start with https:// (or http://).`);
+        actions.push({ type: "webhook", url: (a.url ?? "").trim() });
+        break;
+      case "extension": {
+        const def = typeof a.action === "string" ? getAutomationAction(a.action) : void 0;
+        const params = a.params && typeof a.params === "object" && !Array.isArray(a.params) ? { ...a.params } : {};
+        if (!def) {
+          const known = listAutomationActions().map((d) => d.id);
+          errors.push(`${n}: unknown extension action "${String(a.action)}"${known.length ? `. Available: ${known.join(", ")}` : " (is its extension installed and enabled?)"}.`);
+        } else {
+          if (object && def.objects?.length && !def.objects.includes(object.id)) errors.push(`${n}: "${def.id}" doesn't apply to ${object.labelPlural}.`);
+          for (const p of def.params ?? []) {
+            if (p.required && (params[p.id] === void 0 || params[p.id] === null || params[p.id] === "")) errors.push(`${n}: "${p.label}" is required.`);
+          }
+          if (object && def.validate) errors.push(...def.validate(params, object).map((e) => `${n}: ${e}`));
+        }
+        actions.push({ type: "extension", action: String(a.action ?? ""), params });
+        break;
+      }
+      default:
+        errors.push(`${n}: unknown action "${String(a?.type)}". Actions: ${ACTION_TYPES.join(", ")}.`);
+    }
+  }
+  if (errors.length) throw new OpsError("validation", errors.join(" "), errors);
+  return { name, enabled: input.enabled ?? true, object: input.object, trigger, conditions, actions };
+}
+async function createAutomation(ctx, input, opts = {}) {
+  assertCan(ctx, "automations.write");
+  const valid = validateAutomation(ctx, input);
+  const now = ctx.now();
+  const id = opts.id ?? newId(now);
+  if (ctx.store.get("automations", id)) throw new OpsError("conflict", `Automation "${id}" already exists.`);
+  const doc = { id, name: valid.name, enabled: valid.enabled ?? true, object: valid.object, trigger: valid.trigger, conditions: valid.conditions ?? [], actions: valid.actions, createdAt: now, updatedAt: now };
+  await ctx.store.write([{ op: "set", collection: "automations", doc: asDoc(doc) }], { message: `Create automation ${valid.name}` });
+  return getAutomation(ctx, id);
+}
+async function updateAutomation(ctx, id, patch) {
+  assertCan(ctx, "automations.write");
+  const current = thaw(getAutomation(ctx, id));
+  const valid = validateAutomation(ctx, {
+    name: patch.name ?? current.name,
+    enabled: patch.enabled ?? current.enabled,
+    object: patch.object ?? current.object,
+    trigger: patch.trigger ?? current.trigger,
+    conditions: patch.conditions ?? current.conditions,
+    actions: patch.actions ?? current.actions
+  });
+  const next = { ...current, ...valid, enabled: valid.enabled ?? true, conditions: valid.conditions ?? [], updatedAt: ctx.now() };
+  await ctx.store.write([{ op: "set", collection: "automations", doc: asDoc(next) }], { message: `Update automation ${valid.name}` });
+  return getAutomation(ctx, id);
+}
+async function setAutomationEnabled(ctx, id, enabled) {
+  assertCan(ctx, "automations.write");
+  getAutomation(ctx, id);
+  await ctx.store.write([{ op: "patch", collection: "automations", id, fields: { enabled, updatedAt: ctx.now() } }], { message: `${enabled ? "Enable" : "Disable"} automation` });
+  return getAutomation(ctx, id);
+}
+async function deleteAutomation(ctx, id, opts = {}) {
+  assertCan(ctx, "automations.write");
+  getAutomation(ctx, id);
+  const runs = opts.keepRuns ? [] : automationRunsOf(ctx.store).filter((r) => r.automationId === id);
+  await ctx.store.write(
+    [{ op: "delete", collection: "automations", id }, ...runs.map((r) => ({ op: "delete", collection: "automationRuns", id: r.id }))],
+    { message: "Delete automation" }
+  );
+  return { id, deletedRuns: runs.length };
+}
+async function duplicateAutomation(ctx, id) {
+  const a = getAutomation(ctx, id);
+  return createAutomation(ctx, { name: `${a.name} (copy)`, enabled: false, object: a.object, trigger: thaw(a.trigger), conditions: thaw(a.conditions), actions: thaw(a.actions) });
+}
+async function createAutomationFromTemplate(ctx, templateId, overrides = {}) {
+  const template = findAutomationTemplate(templateId);
+  if (!template) throw new OpsError("notFound", `Unknown automation template "${templateId}". Templates: ${AUTOMATION_TEMPLATES.map((t) => t.id).join(", ")}.`);
+  return createAutomation(ctx, { ...template.build(), ...overrides });
+}
+async function clearAutomationRuns(ctx, opts = {}) {
+  assertCan(ctx, "automations.write");
+  const runs = automationRunsOf(ctx.store).filter((r) => !opts.automationId || r.automationId === opts.automationId);
+  if (runs.length) await ctx.store.write(runs.map((r) => ({ op: "delete", collection: "automationRuns", id: r.id })), { message: "Clear automation runs" });
+  return { deleted: runs.length };
+}
+async function pruneAutomationRuns(ctx, keep = MAX_AUTOMATION_RUNS) {
+  const runs = listAutomationRuns(ctx);
+  const doomed = runs.slice(keep);
+  if (doomed.length) await ctx.store.write(doomed.map((r) => ({ op: "delete", collection: "automationRuns", id: r.id })), { message: "Prune automation runs" });
+  return { deleted: doomed.length };
+}
+function conditionsMatch(ctx, automation, record, object) {
+  if (!automation.conditions?.length) return true;
+  const qctx = queryContext(ctx, object);
+  return automation.conditions.every((f) => matchesFilter(record, f, qctx));
+}
+function stageMatches(ctx, record, to, stageId) {
+  if (to === void 0 || to === null || to === "") return true;
+  const wanted = String(to).toLowerCase();
+  if (stageId.toLowerCase() === wanted) return true;
+  const pipeline = pipelineOfRecord(ctx, record);
+  const stage = pipeline?.stages.find((s) => s.id === stageId);
+  return !!stage && (stage.kind === wanted || stage.label.toLowerCase() === wanted);
+}
+function triggerMatches(ctx, automation, event) {
+  const t = automation.trigger;
+  const record = "record" in event.payload ? event.payload.record : void 0;
+  if (!record || record.object !== automation.object) return false;
+  switch (event.type) {
+    case "record.created":
+      return t.type === "record.created";
+    case "record.updated": {
+      const changed = event.payload.changed;
+      if (t.type === "record.updated") return !t.field || changed.includes(t.field);
+      if (t.type !== "field.changed" || !t.field || !changed.includes(t.field)) return false;
+      if (t.to === void 0 || t.to === null || t.to === "") return true;
+      const object = objectOf(ctx.store, record.object);
+      return !!object && matchesFilter(record, { field: t.field, op: "eq", value: t.to }, queryContext(ctx, object));
+    }
+    case "stage.changed":
+      return t.type === "stage.changed" && stageMatches(ctx, record, t.to, event.payload.to);
+    default:
+      return false;
+  }
+}
+function eligibleOwners(ctx) {
+  return usersOf(ctx.store).filter((u) => !u.disabled && u.role !== "viewer").sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+}
+function describeAction(ctx, action, record, object) {
+  switch (action.type) {
+    case "createTask": {
+      const assignee = action.assignTo && action.assignTo !== "owner" ? action.assignTo : record.ownerId;
+      return `Create task "${renderTemplate(ctx, action.title, record, object)}"${action.dueInDays !== void 0 ? ` due in ${action.dueInDays} day(s)` : ""}${assignee ? ` for ${userOf(ctx.store, assignee)?.name ?? assignee}` : ""}`;
+    }
+    case "updateField":
+      return `Set ${resolveField(object, action.field)?.label ?? action.field} to ${JSON.stringify(typeof action.value === "string" ? renderTemplate(ctx, action.value, record, object) : action.value ?? null)}`;
+    case "addNote":
+      return `Add note "${renderTemplate(ctx, action.body, record, object).slice(0, 120)}"`;
+    case "assignOwner":
+      return action.userId === "roundRobin" ? "Assign owner (round robin)" : `Assign owner ${userOf(ctx.store, action.userId)?.name ?? action.userId}`;
+    case "webhook":
+      return `POST to ${action.url}`;
+    case "extension": {
+      const def = getAutomationAction(action.action);
+      if (!def) return `Run ${action.action} (not available)`;
+      const params = renderParams(ctx, def, action.params ?? {}, record, object);
+      return def.describe?.({ params, record, object }) ?? `Run ${def.label}`;
+    }
+  }
+}
+function renderParams(ctx, def, params, record, object) {
+  const out = { ...params };
+  for (const p of def.params ?? []) {
+    if (p.template && typeof out[p.id] === "string") out[p.id] = renderTemplate(ctx, out[p.id], record, object);
+  }
+  return out;
+}
+async function postWebhook(url, body) {
+  const fetchImpl = webhookFetch ?? (typeof fetch === "function" ? fetch : void 0);
+  if (!fetchImpl) throw new Error("fetch is not available in this environment.");
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+  const timer = controller ? setTimeout(() => controller.abort(), 1e4) : void 0;
+  try {
+    const res = await fetchImpl(url, { method: "POST", headers: { "content-type": "text/plain;charset=UTF-8" }, body: JSON.stringify(body), signal: controller?.signal });
+    if (!res.ok && res.status !== 0) throw new Error(`Webhook answered HTTP ${res.status}.`);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function executeAction(ctx, actx, automation, action, recordId, object, trigger) {
+  const record = requireRecord(ctx.store, recordId);
+  switch (action.type) {
+    case "createTask": {
+      const assigneeId = action.assignTo && action.assignTo !== "owner" ? action.assignTo : record.ownerId;
+      const task = await createTask(actx, {
+        title: renderTemplate(ctx, action.title, record, object),
+        dueAt: action.dueInDays !== void 0 ? ctx.now() + action.dueInDays * DAY : void 0,
+        assigneeId: assigneeId && userOf(ctx.store, assigneeId) ? assigneeId : void 0,
+        targets: [{ object: record.object, id: record.id }]
+      });
+      return `Task ${task.id} created`;
+    }
+    case "updateField": {
+      const value = typeof action.value === "string" ? renderTemplate(ctx, action.value, record, object) : action.value;
+      await updateRecord(actx, record.id, { [action.field]: value ?? null });
+      return `${action.field} updated`;
+    }
+    case "addNote": {
+      const note = await addNote(actx, { object: record.object, id: record.id }, renderTemplate(ctx, action.body, record, object), automation.name);
+      return `Note ${note.id} added`;
+    }
+    case "assignOwner": {
+      let userId = action.userId;
+      if (userId === "roundRobin") {
+        const pool = eligibleOwners(ctx);
+        if (!pool.length) throw new Error("No active admin or member to assign.");
+        const doc = ctx.store.get("automations", automation.id);
+        const cursor = doc?.roundRobinCursor ?? 0;
+        userId = pool[cursor % pool.length].id;
+        await ctx.store.write([{ op: "patch", collection: "automations", id: automation.id, fields: { roundRobinCursor: (cursor + 1) % pool.length } }], { message: "Automation round robin" });
+      }
+      await setRecordOwner(actx, record.id, userId);
+      return `Owner set to ${userOf(ctx.store, userId)?.name ?? userId}`;
+    }
+    case "webhook": {
+      await postWebhook(action.url, {
+        automation: { id: automation.id, name: automation.name },
+        trigger,
+        firedAt: new Date(ctx.now()).toISOString(),
+        record: summarizeForWebhook(ctx, record, object)
+      });
+      return `POST ${action.url} ok`;
+    }
+    case "extension": {
+      const def = getAutomationAction(action.action);
+      if (!def) throw new Error(`Action "${action.action}" is not available (is its extension installed and enabled?).`);
+      const params = renderParams(ctx, def, action.params ?? {}, record, object);
+      const message = await def.run(actx, { params, record, object, automation, trigger });
+      return typeof message === "string" && message ? message : `${def.id} done`;
+    }
+  }
+}
+async function runOne(ctx, input) {
+  const { automation, record, object, dryRun } = input;
+  const startedAt = ctx.now();
+  const run = {
+    id: newId(startedAt),
+    automationId: automation.id,
+    recordId: record.id,
+    startedAt,
+    status: "ok",
+    trigger: automation.trigger.type,
+    ...input.key ? { key: input.key } : {},
+    ...dryRun ? { dryRun: true } : {}
+  };
+  const results = [];
+  if (dryRun) {
+    const plans = automation.actions.map((a) => ({ action: a, describe: describeAction(ctx, a, record, object) }));
+    run.actions = plans.map((p) => ({ type: p.action.type, ok: true, message: p.describe }));
+    run.finishedAt = ctx.now();
+    run.message = "Dry run — nothing was written.";
+    return run;
+  }
+  const actx = { ...ctx, user: null, depth: (ctx.depth ?? 0) + 1 };
+  for (const action of automation.actions) {
+    try {
+      const message = await executeAction(ctx, actx, automation, action, record.id, object, String(input.trigger));
+      results.push({ type: action.type, ok: true, message });
+    } catch (err) {
+      results.push({ type: action.type, ok: false, message: err.message ?? String(err) });
+    }
+  }
+  run.actions = results;
+  run.finishedAt = ctx.now();
+  const failed = results.filter((r) => !r.ok);
+  if (failed.length) {
+    run.status = "error";
+    run.message = failed.map((f) => `${f.type}: ${f.message}`).join(" · ");
+  }
+  await ctx.store.write(
+    [
+      { op: "set", collection: "automationRuns", doc: asDoc(run) },
+      { op: "patch", collection: "automations", id: automation.id, fields: { lastRunAt: run.finishedAt } }
+    ],
+    { message: `Automation run: ${automation.name}` }
+  );
+  ctx.log?.(`automation "${automation.name}" on ${record.id}: ${run.status}`);
+  return run;
+}
+async function logSkipped(ctx, automation, recordId, message) {
+  const now = ctx.now();
+  const run = { id: newId(now), automationId: automation.id, ...recordId ? { recordId } : {}, startedAt: now, finishedAt: now, status: "skipped", message, trigger: automation.trigger.type };
+  await ctx.store.write([{ op: "set", collection: "automationRuns", doc: asDoc(run) }], { message: `Automation skipped: ${automation.name}` });
+  return run;
+}
+function tally(runs) {
+  return {
+    ran: runs.filter((r) => r.status === "ok").length,
+    skipped: runs.filter((r) => r.status === "skipped").length,
+    errors: runs.filter((r) => r.status === "error").length,
+    runs
+  };
+}
+async function runAutomationEvent(ctx, event) {
+  const record = "record" in event.payload ? event.payload.record : void 0;
+  if (!record || record.deletedAt) return tally([]);
+  const candidates = automationsOf(ctx.store).filter((a) => a.enabled && EVENT_TRIGGERS.includes(a.trigger.type) && triggerMatches(ctx, a, event));
+  if (!candidates.length) return tally([]);
+  const object = objectOf(ctx.store, record.object);
+  if (!object) return tally([]);
+  const runs = [];
+  const depth = ctx.depth ?? 0;
+  for (const automation of candidates) {
+    if (depth >= MAX_AUTOMATION_DEPTH) {
+      runs.push(await logSkipped(ctx, automation, record.id, `Loop protection: nested automation depth ${depth} reached the limit (${MAX_AUTOMATION_DEPTH}).`));
+      continue;
+    }
+    const current = recordOf(ctx.store, record.id);
+    if (!current || current.deletedAt) continue;
+    if (!conditionsMatch(ctx, automation, current, object)) continue;
+    runs.push(await runOne(ctx, { automation, record: current, object, trigger: event.type }));
+  }
+  return tally(runs);
+}
+function installAutomations(registry = plugins) {
+  const types = ["record.created", "record.updated", "stage.changed"];
+  const offs = types.map(
+    (type) => registry.addAction(type, async (ctx, payload) => {
+      await runAutomationEvent(ctx, { type, payload });
+    }, 50)
+  );
+  return () => offs.forEach((off) => off());
+}
+function lastTouchedAt(ctx, record) {
+  return Math.max(lastActivityAt(ctx, record.id) ?? 0, record.updatedAt, record.createdAt);
+}
+async function runScheduled(ctx, opts = {}) {
+  assertCan(ctx, "automations.run");
+  const now = ctx.now();
+  const automations = automationsOf(ctx.store).filter(
+    (a) => SCHEDULED_TRIGGERS.includes(a.trigger.type) && (opts.automationId ? a.id === opts.automationId : a.enabled)
+  );
+  if (opts.automationId && !automations.length) {
+    const a = getAutomation(ctx, opts.automationId);
+    throw new OpsError("invalid", `Automation "${a.name}" has a ${a.trigger.type} trigger — only schedule / inactivity automations run on a schedule.`);
+  }
+  const knownKeys = new Set(automationRunsOf(ctx.store).map((r) => r.key).filter((k) => !!k));
+  const runs = [];
+  for (const automation of automations) {
+    const object = objectOf(ctx.store, automation.object);
+    if (!object) continue;
+    const t = automation.trigger;
+    let slotKey = null;
+    if (t.type === "schedule") {
+      const every = Math.max(1, t.everyHours ?? 24) * HOUR;
+      if (!opts.force && automation.lastRunAt && now - automation.lastRunAt < every) continue;
+      slotKey = `${automation.id}:schedule:${Math.floor(now / every)}`;
+    }
+    const sysCtx = { ...ctx, depth: ctx.depth ?? 0 };
+    let matched = 0;
+    for (const record of recordsOf(ctx.store, object.id)) {
+      let key;
+      if (t.type === "inactivity") {
+        const since = lastTouchedAt(ctx, record);
+        if (now - since < (t.days ?? 14) * DAY) continue;
+        key = `${automation.id}:inactivity:${record.id}:${since}`;
+      } else {
+        key = `${slotKey}:${record.id}${opts.force ? `:${now}` : ""}`;
+      }
+      if (knownKeys.has(key)) continue;
+      if (!conditionsMatch(ctx, automation, record, object)) continue;
+      matched++;
+      const run = await runOne(sysCtx, { automation, record, object, trigger: t.type, key, dryRun: opts.dryRun });
+      knownKeys.add(key);
+      runs.push(run);
+    }
+    if (t.type === "schedule" && !matched && !opts.dryRun) {
+      await ctx.store.write([{ op: "patch", collection: "automations", id: automation.id, fields: { lastRunAt: now } }], { message: "Automation schedule tick" });
+    }
+  }
+  if (!opts.dryRun && automationRunsOf(ctx.store).length > MAX_AUTOMATION_RUNS) await pruneAutomationRuns(ctx);
+  return tally(runs);
+}
+async function testAutomation(ctx, automation, recordId, opts = {}) {
+  assertCan(ctx, "automations.run");
+  const dryRun = opts.dryRun !== false;
+  if (!dryRun) assertCan(ctx, "records.write");
+  const record = requireRecord(ctx.store, recordId);
+  const object = requireObject(ctx.store, record.object);
+  const def = {
+    id: automation.id ?? "test",
+    name: automation.name || "Test",
+    enabled: true,
+    object: automation.object,
+    trigger: automation.trigger,
+    conditions: automation.conditions ?? [],
+    actions: automation.actions
+  };
+  if (def.object !== record.object) throw new OpsError("validation", `This automation applies to ${def.object}; the record is a ${object.labelSingular}.`);
+  const qctx = queryContext(ctx, object);
+  const failedConditions = def.conditions.filter((f) => !matchesFilter(record, f, qctx));
+  if (failedConditions.length) {
+    const now = ctx.now();
+    return {
+      matched: false,
+      failedConditions,
+      run: { id: "test", automationId: def.id, recordId, startedAt: now, finishedAt: now, status: "skipped", message: "Conditions don't match this record.", dryRun }
+    };
+  }
+  const run = await runOne(ctx, { automation: def, record, object, trigger: "manual", dryRun });
+  return { matched: true, run, failedConditions: [] };
+}
+function scheduledCandidates(ctx, automationId) {
+  const a = getAutomation(ctx, automationId);
+  const object = objectOf(ctx.store, a.object);
+  if (!object) return [];
+  return recordsOf(ctx.store, object.id).filter((r) => {
+    if (a.trigger.type === "inactivity" && ctx.now() - lastTouchedAt(ctx, r) < (a.trigger.days ?? 14) * DAY) return false;
+    return conditionsMatch(ctx, a, r, object);
+  });
+}
+function automationAssignees(ctx) {
+  return eligibleOwners(ctx).map((u) => ({ id: u.id, name: u.name, email: normalizeEmail(u.email) }));
+}
+export {
+  ACTION_TYPES,
+  AUTOMATION_TEMPLATES,
+  EVENT_TRIGGERS,
+  MAX_AUTOMATION_DEPTH,
+  MAX_AUTOMATION_RUNS,
+  SCHEDULED_TRIGGERS,
+  TRIGGER_TYPES,
+  automationAssignees,
+  clearAutomationRuns,
+  createAutomation,
+  createAutomationFromTemplate,
+  deleteAutomation,
+  duplicateAutomation,
+  findAutomationTemplate,
+  getAutomation,
+  getAutomationAction,
+  installAutomations,
+  lastTouchedAt,
+  listAutomationActions,
+  listAutomationRuns,
+  listAutomations,
+  pruneAutomationRuns,
+  registerAutomationAction,
+  renderTemplate,
+  runAutomationEvent,
+  runScheduled,
+  scheduledCandidates,
+  setAutomationEnabled,
+  setAutomationFetch,
+  subscribeAutomationActions,
+  templatePlaceholders,
+  testAutomation,
+  triggerMatches,
+  updateAutomation,
+  validateAutomation
+};