@agent-native/core 0.123.0 → 0.123.1

package/corpus/templates/crm/actions/estimate-crm-enrichment.ts

@@ -0,0 +1,229 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq, gte, inArray } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  CrmEnrichmentScopeError,
+  MAX_ENRICHMENT_RECORDS_PER_RUN,
+  assertRecordCountWithinCap,
+  currentSpendPeriodStart,
+  estimateEnrichment,
+  evaluateEnrichmentBudget,
+  resolveEnrichmentBudgetUnits,
+  resolveEnrichmentScope,
+  type CrmEnrichmentScopeKind,
+  type CrmSpendToDate,
+} from "../server/lib/enrichment-cost.js";
+import {
+  CRM_ENRICHMENT_SLOTS,
+  type CrmEnrichmentSlot,
+} from "../server/lib/enrichment-slots.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+
+export const scopeInput = {
+  scopeKind: z.enum(["object", "list", "records"]).default("records"),
+  targetId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Object type for scopeKind=object, list id for scopeKind=list."),
+  recordIds: z
+    .array(z.string().trim().min(1).max(128))
+    .max(MAX_ENRICHMENT_RECORDS_PER_RUN)
+    .optional()
+    .describe("Required for scopeKind=records."),
+  slots: z
+    .array(z.enum(CRM_ENRICHMENT_SLOTS))
+    .min(1)
+    .optional()
+    .describe("Defaults to every slot. The phase decides which of them run."),
+};
+
+export default defineAction({
+  description:
+    "Estimate what an enrichment run will cost BEFORE spending anything, with a per-slot line-item breakdown and your period-to-date spend. Read-only: it starts nothing. Phase verify prices the free evidence pass; phase spend prices the paid contact pass over the records you intend to approve. Spend to date is reported twice — actorUnits is yours and is what the budget cap applies to, workspaceUnits is everyone's and is context only. Quote the estimate to the user before calling run-crm-enrichment, which echoes back this same estimate.",
+  schema: z.object({
+    phase: z.enum(["verify", "spend"]),
+    ...scopeInput,
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args, ctx?: ActionRunContext) => {
+    const ownership = requireCrmScope(ctx);
+    const recordIds = await resolveScopeRecordIds(args);
+    assertRecordCountWithinCap(recordIds.length);
+    const scope = await resolveEnrichmentScope({
+      kind: args.scopeKind,
+      targetId: args.targetId,
+      recordIds,
+    });
+
+    const estimate = estimateEnrichment({
+      phase: args.phase,
+      slots: (args.slots ?? CRM_ENRICHMENT_SLOTS) as CrmEnrichmentSlot[],
+      recordCount: recordIds.length,
+    });
+
+    const periodStart = currentSpendPeriodStart();
+    const spendToDate = await readEnrichmentSpendToDate({
+      ownerEmail: ownership.ownerEmail,
+      periodStart,
+    });
+    const budget = evaluateEnrichmentBudget({
+      estimatedUnits: estimate.totalCost,
+      spendToDate,
+      capUnits: resolveEnrichmentBudgetUnits(),
+      periodStart,
+    });
+
+    return { scope, recordCount: recordIds.length, estimate, budget };
+  },
+});
+
+/**
+ * The records a scope resolves to, access-scoped.
+ *
+ * An explicit record id that does not resolve is an error, not a silent
+ * omission: quoting a price for four records when the user named five is a
+ * quote for a different job.
+ */
+export async function resolveScopeRecordIds(args: {
+  scopeKind: CrmEnrichmentScopeKind;
+  targetId?: string;
+  recordIds?: string[];
+}): Promise<string[]> {
+  const db = getDb();
+  if (args.scopeKind === "records") {
+    const requested = [...new Set(args.recordIds ?? [])];
+    if (requested.length === 0) {
+      throw new CrmEnrichmentScopeError(
+        "crm-enrichment-scope-empty",
+        "scopeKind=records needs at least one record id.",
+      );
+    }
+    const rows = await db
+      .select({ id: schema.crmRecords.id })
+      .from(schema.crmRecords)
+      .where(
+        and(
+          inArray(schema.crmRecords.id, requested),
+          eq(schema.crmRecords.tombstone, false),
+          accessFilter(schema.crmRecords, schema.crmRecordShares),
+        ),
+      );
+    const found = new Set(rows.map((row) => row.id));
+    const missing = requested.filter((id) => !found.has(id));
+    if (missing.length > 0) {
+      throw new CrmEnrichmentScopeError(
+        "crm-enrichment-scope-record-not-readable",
+        `These CRM records were not found or are not readable by you: ${missing.join(", ")}.`,
+      );
+    }
+    return requested;
+  }
+
+  if (args.scopeKind === "list") {
+    if (!args.targetId) {
+      throw new CrmEnrichmentScopeError(
+        "crm-enrichment-scope-target-required",
+        "scopeKind=list needs a targetId.",
+      );
+    }
+    const rows = await db
+      .select({ recordId: schema.crmListEntries.recordId })
+      .from(schema.crmListEntries)
+      .where(
+        and(
+          eq(schema.crmListEntries.listId, args.targetId),
+          accessFilter(schema.crmListEntries, schema.crmListEntryShares),
+        ),
+      )
+      .limit(MAX_ENRICHMENT_RECORDS_PER_RUN + 1);
+    // A record may hold several entries in one list; it is still one record to enrich.
+    return [...new Set(rows.map((row) => row.recordId))];
+  }
+
+  if (!args.targetId) {
+    throw new CrmEnrichmentScopeError(
+      "crm-enrichment-scope-target-required",
+      "scopeKind=object needs a targetId.",
+    );
+  }
+  const rows = await db
+    .select({ id: schema.crmRecords.id })
+    .from(schema.crmRecords)
+    .where(
+      and(
+        eq(schema.crmRecords.objectType, args.targetId),
+        eq(schema.crmRecords.tombstone, false),
+        accessFilter(schema.crmRecords, schema.crmRecordShares),
+      ),
+    )
+    .limit(MAX_ENRICHMENT_RECORDS_PER_RUN + 1);
+  return rows.map((row) => row.id);
+}
+
+/**
+ * Spend since the period start, per actor and across the workspace.
+ *
+ * A run still in flight counts at its estimate, not at zero: otherwise ten
+ * concurrent launches all see the same pre-spend total and every one of them
+ * passes a cap they collectively blow through.
+ */
+export async function readEnrichmentSpendToDate(input: {
+  ownerEmail: string;
+  periodStart: string;
+}): Promise<CrmSpendToDate> {
+  const rows = await getDb()
+    .select({
+      id: schema.crmEnrichmentRuns.id,
+      ownerEmail: schema.crmEnrichmentRuns.ownerEmail,
+      status: schema.crmEnrichmentRuns.status,
+      costUnits: schema.crmEnrichmentRuns.costUnits,
+      estimateJson: schema.crmEnrichmentRuns.estimateJson,
+    })
+    .from(schema.crmEnrichmentRuns)
+    .where(
+      and(
+        gte(schema.crmEnrichmentRuns.startedAt, input.periodStart),
+        accessFilter(schema.crmEnrichmentRuns, schema.crmEnrichmentRunShares),
+      ),
+    );
+
+  let actorUnits = 0;
+  let workspaceUnits = 0;
+  for (const row of rows) {
+    if (row.status === "failed") continue;
+    const units = row.costUnits ?? estimatedUnitsOf(row.id, row.estimateJson);
+    workspaceUnits += units;
+    if (row.ownerEmail === input.ownerEmail) actorUnits += units;
+  }
+  return { actorUnits, workspaceUnits };
+}
+
+/** An unreadable estimate throws — an unknown cost must not be counted as zero. */
+function estimatedUnitsOf(runId: string, estimateJson: string): number {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(estimateJson);
+  } catch {
+    throw new Error(
+      `Enrichment run ${runId} has an unreadable estimate_json, so period-to-date spend cannot be totalled. Repair or fail the run.`,
+    );
+  }
+  const total =
+    parsed && typeof parsed === "object"
+      ? (parsed as Record<string, unknown>).totalCost
+      : undefined;
+  if (total === undefined || total === null) return 0;
+  if (typeof total !== "number" || !Number.isFinite(total)) {
+    throw new Error(
+      `Enrichment run ${runId} has a non-numeric estimate total, so period-to-date spend cannot be totalled.`,
+    );
+  }
+  return total;
+}

package/corpus/templates/crm/actions/find-crm-duplicates.ts

@@ -0,0 +1,87 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, desc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  findCrmDuplicateCandidates,
+  CRM_DUPLICATE_MATCH_REASONS,
+} from "../server/lib/dedupe.js";
+
+const MAX_SEEDS = 25;
+
+export default defineAction({
+  description:
+    "Find likely duplicate CRM records and say WHY each pair matched. Checks exact email, company domain, shared email root domain, and normalized name plus location, using indexed sub-field columns. Returns scored candidates with a match reason and confidence per candidate; it never merges anything and never changes a record. Pass recordIds to check specific records, or omit them to check the most recently updated records of an object type.",
+  schema: z.object({
+    recordIds: z
+      .array(z.string().trim().min(1).max(128))
+      .max(MAX_SEEDS)
+      .optional()
+      .describe("Records to check. Omit to scan the most recent records."),
+    objectType: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .optional()
+      .describe("Restrict an automatic scan to one object type."),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_SEEDS)
+      .default(10)
+      .describe("How many records to check when recordIds is omitted."),
+    candidatesPerRecord: z.coerce.number().int().min(1).max(20).default(5),
+    minConfidence: z.coerce.number().min(0).max(1).default(0.4),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const db = getDb();
+
+    let recordIds = args.recordIds ?? [];
+    if (!recordIds.length) {
+      const recent = await db
+        .select({ id: schema.crmRecords.id })
+        .from(schema.crmRecords)
+        .where(
+          and(
+            eq(schema.crmRecords.tombstone, false),
+            ...(args.objectType
+              ? [eq(schema.crmRecords.objectType, args.objectType)]
+              : []),
+            accessFilter(schema.crmRecords, schema.crmRecordShares),
+          ),
+        )
+        .orderBy(desc(schema.crmRecords.updatedAt))
+        .limit(args.limit);
+      recordIds = recent.map((row) => row.id);
+    }
+
+    const seeds = await findCrmDuplicateCandidates({
+      db,
+      recordIds,
+      limit: args.candidatesPerRecord,
+      minConfidence: args.minConfidence,
+    });
+
+    // Requested ids that produced no seed were not readable by this caller.
+    // Reporting them as "no duplicates" would be the same failure this action
+    // exists to prevent, so they come back named.
+    const found = new Set(seeds.map((seed) => seed.recordId));
+    const unreadableRecordIds = recordIds.filter((id) => !found.has(id));
+
+    return {
+      checked: seeds.length,
+      matchReasons: [...CRM_DUPLICATE_MATCH_REASONS],
+      unreadableRecordIds,
+      records: seeds.filter((seed) => seed.candidates.length > 0),
+      cleanRecordIds: seeds
+        .filter((seed) => seed.candidates.length === 0)
+        .map((seed) => seed.recordId),
+    };
+  },
+});

package/corpus/templates/crm/actions/get-crm-automation-recipe.ts

@@ -0,0 +1,36 @@
+import { defineAction } from "@agent-native/core/action";
+import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  CLIPS_CALL_EVIDENCE_RECIPE_ID,
+  buildClipsCallEvidenceRecipe,
+} from "../shared/crm-automation-recipes.js";
+
+export default defineAction({
+  description:
+    "Return the default-off Clips call-evidence review recipe for one explicitly selected CRM record. The recipe never passes media, transcripts, or an event URL into CRM.",
+  schema: z.object({
+    recipeId: z
+      .literal(CLIPS_CALL_EVIDENCE_RECIPE_ID)
+      .default(CLIPS_CALL_EVIDENCE_RECIPE_ID),
+    recordId: z.string().trim().min(1).max(128),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ recordId }) => {
+    await assertAccess("crm-record", recordId, "viewer");
+    const [record] = await getDb()
+      .select({ displayName: schema.crmRecords.displayName })
+      .from(schema.crmRecords)
+      .where(eq(schema.crmRecords.id, recordId))
+      .limit(1);
+    if (!record) throw new Error("CRM record was not found.");
+    return buildClipsCallEvidenceRecipe({
+      recordId,
+      recordLabel: record.displayName,
+    });
+  },
+});

package/corpus/templates/crm/actions/get-crm-dashboard-panel.ts

@@ -0,0 +1,35 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { createProgramPanelSourceResolver } from "@agent-native/core/dashboard-storage";
+import { z } from "zod";
+
+import { crmDashboardStore } from "../server/db/index.js";
+import { CRM_APP_ID } from "../server/lib/provider-api.js";
+import { requireDashboardAccess } from "./_crm-dashboard.js";
+import { initCrmDataPrograms } from "./_crm-data-program-actions.js";
+
+const programResolver = createProgramPanelSourceResolver({ appId: CRM_APP_ID });
+
+export default defineAction({
+  description:
+    "Resolve one program-backed panel from an access-scoped CRM dashboard for the dashboard UI.",
+  schema: z.object({
+    dashboardId: z.string().trim().min(1).max(200),
+    panelId: z.string().trim().min(1).max(120),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  agentTool: false,
+  toolCallable: false,
+  run: async ({ dashboardId, panelId }, ctx?: ActionRunContext) => {
+    const access = requireDashboardAccess(ctx);
+    const dashboard = await crmDashboardStore.get(dashboardId, access);
+    if (!dashboard) throw new Error("CRM dashboard was not found.");
+    const panel = dashboard.config.panels.find((item) => item.id === panelId);
+    if (!panel) throw new Error("CRM dashboard panel was not found.");
+    initCrmDataPrograms();
+    return programResolver.resolve(
+      { source: panel.source, query: panel.query },
+      { userEmail: access.userEmail, orgId: access.orgId ?? null },
+    );
+  },
+});

package/corpus/templates/crm/actions/get-crm-dashboard.ts

@@ -0,0 +1,14 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { crmDashboardStore } from "../server/db/index.js";
+import { requireDashboardAccess } from "./_crm-dashboard.js";
+
+export default defineAction({
+  description: "Get one access-scoped CRM dashboard by ID.",
+  schema: z.object({ id: z.string().trim().min(1).max(200) }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: ({ id }, ctx?: ActionRunContext) =>
+    crmDashboardStore.get(id, requireDashboardAccess(ctx)),
+});

package/corpus/templates/crm/actions/get-crm-overview.ts

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { getCrmOverview } from "../server/db/crm-store.js";
+
+export default defineAction({
+  description:
+    "Return a compact, access-scoped CRM work overview: open follow-up tasks, recently active mirrored records, and pending write proposals.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: () => getCrmOverview(),
+});

package/corpus/templates/crm/actions/get-crm-pipeline-data.ts

@@ -0,0 +1,61 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, asc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { requireDashboardAccess } from "./_crm-dashboard.js";
+
+const MAX_PIPELINE_RECORDS = 500;
+
+export default defineAction({
+  description:
+    "Return bounded, access-scoped pipeline totals grouped by opportunity stage. This is the CRM-owned read source for the Pipeline dashboard data program.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (_args, ctx?: ActionRunContext) => {
+    const access = requireDashboardAccess(ctx);
+    const records = await getDb()
+      .select({
+        stage: schema.crmRecords.stage,
+        amount: schema.crmRecords.amount,
+      })
+      .from(schema.crmRecords)
+      .where(
+        and(
+          eq(schema.crmRecords.kind, "opportunity"),
+          eq(schema.crmRecords.tombstone, false),
+          accessFilter(schema.crmRecords, schema.crmRecordShares, access),
+        ),
+      )
+      .orderBy(asc(schema.crmRecords.stage))
+      .limit(MAX_PIPELINE_RECORDS);
+
+    const stages = new Map<
+      string,
+      { stage: string; pipelineValue: number; opportunities: number }
+    >();
+    for (const record of records) {
+      const stage = record.stage?.trim() || "Unstaged";
+      const total = stages.get(stage) ?? {
+        stage,
+        pipelineValue: 0,
+        opportunities: 0,
+      };
+      total.pipelineValue += Number.isFinite(record.amount)
+        ? record.amount!
+        : 0;
+      total.opportunities += 1;
+      stages.set(stage, total);
+    }
+    const rows = [...stages.values()].sort((a, b) =>
+      a.stage.localeCompare(b.stage),
+    );
+    return {
+      rows,
+      truncated: records.length === MAX_PIPELINE_RECORDS,
+      sourceRecordLimit: MAX_PIPELINE_RECORDS,
+    };
+  },
+});