@agent-native/core 0.122.4 → 0.123.1

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

@@ -0,0 +1,364 @@
+import { defineAction, type ActionRunContext } 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 { requireCrmScope } from "./_crm-action-utils.js";
+
+/**
+ * Everything here is derived from the auth session — there is no per-user CRM
+ * configuration to author, and none should be introduced. "Who am I in this
+ * CRM" is answered from the mirrored owner attribution on the records the caller
+ * already owns.
+ */
+
+/** Records scanned to build the book of business before the answer is partial. */
+const MAX_BOOK_SCAN = 500;
+const MAX_TASK_SCAN = 200;
+const MAX_QUEUE_SCAN = 100;
+
+export type CrmOwnerStatus =
+  | "resolved"
+  | "unmapped"
+  | "ambiguous"
+  | "unreadable"
+  | "not-applicable";
+
+interface OwnerError {
+  code: "crm-owner-ambiguous" | "crm-owner-connection-unhealthy";
+  message: string;
+  connectionId?: string;
+}
+
+interface OwnedRecord {
+  id: string;
+  displayName: string;
+  objectType: string;
+  kind: string;
+  stage: string | null;
+  amount: number | null;
+  currencyCode: string | null;
+  closeDate: string | null;
+  connectionId: string;
+  ownerRemoteId: string | null;
+  ownerName: string | null;
+  nextContactAt: string | null;
+  updatedAt: string;
+}
+
+interface ConnectionHealth {
+  id: string;
+  provider: string;
+  label: string;
+  mode: string;
+  status: string;
+  lastSyncedAt: string | null;
+  lastError: string | null;
+}
+
+/**
+ * Resolve the caller's provider owner identity from their own mirrored records.
+ *
+ * The four non-resolved outcomes are deliberately DIFFERENT values. "No provider
+ * connection", "connected but nothing attributes you to an owner", "the mirror
+ * is stale because a connection is broken", and "you appear under two owner ids"
+ * all render as an empty owner slot if they are flattened, and the third one is
+ * the dangerous case: it would let a broken connection look exactly like an
+ * empty book of business.
+ */
+function resolveWorkspaceOwner(input: {
+  connections: ConnectionHealth[];
+  records: OwnedRecord[];
+}): {
+  ownerStatus: CrmOwnerStatus;
+  owner: {
+    connectionId: string;
+    provider: string;
+    ownerRemoteId: string;
+    ownerName: string | null;
+    recordCount: number;
+  } | null;
+  ownerError?: OwnerError;
+} {
+  const providerConnections = input.connections.filter(
+    (connection) => connection.provider !== "native",
+  );
+  if (!providerConnections.length) {
+    return { ownerStatus: "not-applicable", owner: null };
+  }
+
+  const unhealthy = providerConnections.find(
+    (connection) =>
+      connection.status === "error" || connection.status === "disconnected",
+  );
+  if (unhealthy) {
+    return {
+      ownerStatus: "unreadable",
+      owner: null,
+      ownerError: {
+        code: "crm-owner-connection-unhealthy",
+        message: `Connection "${unhealthy.label}" is ${unhealthy.status}${
+          unhealthy.lastError ? `: ${unhealthy.lastError}` : ""
+        }. Your provider owner identity cannot be determined from a stale mirror — reconnect it before treating this book of business as complete.`,
+        connectionId: unhealthy.id,
+      },
+    };
+  }
+
+  const byOwner = new Map<
+    string,
+    {
+      connectionId: string;
+      ownerRemoteId: string;
+      ownerName: string | null;
+      count: number;
+    }
+  >();
+  for (const record of input.records) {
+    if (!record.ownerRemoteId) continue;
+    const key = `${record.connectionId}:${record.ownerRemoteId}`;
+    const bucket = byOwner.get(key) ?? {
+      connectionId: record.connectionId,
+      ownerRemoteId: record.ownerRemoteId,
+      ownerName: record.ownerName,
+      count: 0,
+    };
+    bucket.count += 1;
+    byOwner.set(key, bucket);
+  }
+
+  const owners = [...byOwner.values()].sort((a, b) => b.count - a.count);
+  if (!owners.length) {
+    return { ownerStatus: "unmapped", owner: null };
+  }
+  if (owners.length > 1) {
+    return {
+      ownerStatus: "ambiguous",
+      owner: null,
+      ownerError: {
+        code: "crm-owner-ambiguous",
+        message: `Your records are attributed to ${owners.length} different provider owner ids (${owners
+          .map((owner) => owner.ownerRemoteId)
+          .join(
+            ", ",
+          )}). Pick the right one in the provider before relying on owner-scoped work.`,
+      },
+    };
+  }
+
+  const [owner] = owners;
+  return {
+    ownerStatus: "resolved",
+    owner: {
+      connectionId: owner.connectionId,
+      provider:
+        providerConnections.find(
+          (connection) => connection.id === owner.connectionId,
+        )?.provider ?? "custom",
+      ownerRemoteId: owner.ownerRemoteId,
+      ownerName: owner.ownerName,
+      recordCount: owner.count,
+    },
+  };
+}
+
+function bucketTaskDue(
+  dueAt: string | null,
+  now: number,
+): "overdue" | "today" | "upcoming" | "undated" {
+  if (!dueAt) return "undated";
+  const due = Date.parse(dueAt);
+  if (!Number.isFinite(due)) return "undated";
+  if (due < now) return "overdue";
+  return due - now <= 24 * 60 * 60 * 1000 ? "today" : "upcoming";
+}
+
+export default defineAction({
+  description:
+    "One-call orientation for the caller: who they are, their provider owner identity, their book of business by stage, follow-up tasks due, pending write proposals, unreviewed signals, and connection health. Everything is derived from the signed-in session with no setup. Call this first when starting CRM work. A provider owner that cannot be determined comes back as ownerStatus plus ownerError — never as an empty book.",
+  schema: z.object({
+    bookLimit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(50)
+      .default(10)
+      .describe("How many of the caller's records to list in full."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args, ctx?: ActionRunContext) => {
+    const scope = requireCrmScope(ctx);
+    const db = getDb();
+    const now = Date.now();
+
+    const connections: ConnectionHealth[] = await db
+      .select({
+        id: schema.crmConnections.id,
+        provider: schema.crmConnections.provider,
+        label: schema.crmConnections.label,
+        mode: schema.crmConnections.mode,
+        status: schema.crmConnections.status,
+        lastSyncedAt: schema.crmConnections.lastSyncedAt,
+        lastError: schema.crmConnections.lastError,
+      })
+      .from(schema.crmConnections)
+      .where(accessFilter(schema.crmConnections, schema.crmConnectionShares))
+      .limit(MAX_QUEUE_SCAN);
+
+    // The book of business is what the caller OWNS, not everything they can
+    // see — a shared org-wide record is somebody else's work.
+    const records: OwnedRecord[] = await db
+      .select({
+        id: schema.crmRecords.id,
+        displayName: schema.crmRecords.displayName,
+        objectType: schema.crmRecords.objectType,
+        kind: schema.crmRecords.kind,
+        stage: schema.crmRecords.stage,
+        amount: schema.crmRecords.amount,
+        currencyCode: schema.crmRecords.currencyCode,
+        closeDate: schema.crmRecords.closeDate,
+        connectionId: schema.crmRecords.connectionId,
+        ownerRemoteId: schema.crmRecords.ownerRemoteId,
+        ownerName: schema.crmRecords.ownerName,
+        nextContactAt: schema.crmRecords.nextContactAt,
+        updatedAt: schema.crmRecords.updatedAt,
+      })
+      .from(schema.crmRecords)
+      .where(
+        and(
+          eq(schema.crmRecords.ownerEmail, scope.ownerEmail),
+          eq(schema.crmRecords.tombstone, false),
+          accessFilter(schema.crmRecords, schema.crmRecordShares),
+        ),
+      )
+      .orderBy(desc(schema.crmRecords.updatedAt))
+      .limit(MAX_BOOK_SCAN + 1);
+
+    // A truncated scan is not a completed one: the counts below would be a
+    // confident understatement, so say so instead of rounding it off.
+    const bookComplete = records.length <= MAX_BOOK_SCAN;
+    const scanned = bookComplete ? records : records.slice(0, MAX_BOOK_SCAN);
+
+    const byStage: Record<string, { records: number; amount: number }> = {};
+    const byKind: Record<string, number> = {};
+    for (const record of scanned) {
+      const stage = record.stage ?? "(unstaged)";
+      const bucket = byStage[stage] ?? { records: 0, amount: 0 };
+      bucket.records += 1;
+      if (record.kind === "opportunity" && typeof record.amount === "number") {
+        bucket.amount += record.amount;
+      }
+      byStage[stage] = bucket;
+      byKind[record.kind] = (byKind[record.kind] ?? 0) + 1;
+    }
+
+    const taskRows = await db
+      .select({
+        id: schema.crmTasks.id,
+        recordId: schema.crmTasks.recordId,
+        title: schema.crmTasks.title,
+        dueAt: schema.crmTasks.dueAt,
+        assignedTo: schema.crmTasks.assignedTo,
+      })
+      .from(schema.crmTasks)
+      .where(
+        and(
+          eq(schema.crmTasks.status, "open"),
+          accessFilter(schema.crmTasks, schema.crmTaskShares),
+        ),
+      )
+      .orderBy(desc(schema.crmTasks.updatedAt))
+      .limit(MAX_TASK_SCAN);
+    const taskCounts = { overdue: 0, today: 0, upcoming: 0, undated: 0 };
+    for (const task of taskRows) {
+      taskCounts[bucketTaskDue(task.dueAt, now)] += 1;
+    }
+
+    const proposals = await db
+      .select({ id: schema.crmMutations.id })
+      .from(schema.crmMutations)
+      .where(
+        and(
+          eq(schema.crmMutations.status, "pending"),
+          accessFilter(schema.crmMutations, schema.crmMutationShares),
+        ),
+      )
+      .limit(MAX_QUEUE_SCAN);
+
+    const signals = await db
+      .select({ id: schema.crmSignals.id })
+      .from(schema.crmSignals)
+      .where(
+        and(
+          eq(schema.crmSignals.reviewStatus, "unreviewed"),
+          accessFilter(schema.crmSignals, schema.crmSignalShares),
+        ),
+      )
+      .limit(MAX_QUEUE_SCAN);
+
+    const ownerResolution = resolveWorkspaceOwner({
+      connections,
+      records: scanned,
+    });
+
+    return {
+      user: {
+        email: scope.ownerEmail,
+        orgId: scope.orgId,
+        visibility: scope.visibility,
+      },
+      ...ownerResolution,
+      book: {
+        recordCount: scanned.length,
+        complete: bookComplete,
+        scanLimit: MAX_BOOK_SCAN,
+        byStage,
+        byKind,
+        needsAttention: scanned
+          .filter(
+            (record) =>
+              record.nextContactAt !== null &&
+              Date.parse(record.nextContactAt) <= now,
+          )
+          .slice(0, args.bookLimit)
+          .map((record) => ({
+            id: record.id,
+            displayName: record.displayName,
+            stage: record.stage,
+            nextContactAt: record.nextContactAt,
+          })),
+        records: scanned.slice(0, args.bookLimit).map((record) => ({
+          id: record.id,
+          displayName: record.displayName,
+          objectType: record.objectType,
+          kind: record.kind,
+          stage: record.stage,
+          amount: record.amount,
+          currencyCode: record.currencyCode,
+          closeDate: record.closeDate,
+          updatedAt: record.updatedAt,
+        })),
+      },
+      tasks: {
+        open: taskRows.length,
+        complete: taskRows.length < MAX_TASK_SCAN,
+        ...taskCounts,
+        next: taskRows
+          .filter((task) => task.dueAt !== null)
+          .sort((a, b) => (a.dueAt ?? "").localeCompare(b.dueAt ?? ""))
+          .slice(0, 5),
+      },
+      proposals: {
+        pending: proposals.length,
+        complete: proposals.length < MAX_QUEUE_SCAN,
+      },
+      signals: {
+        unreviewed: signals.length,
+        complete: signals.length < MAX_QUEUE_SCAN,
+      },
+      connections,
+    };
+  },
+});

package/corpus/templates/crm/actions/install-crm-pipeline-dashboard.ts

@@ -0,0 +1,81 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { upsertDataProgram } from "@agent-native/core/data-programs";
+import { z } from "zod";
+
+import { crmDashboardStore } from "../server/db/index.js";
+import { CRM_APP_ID } from "../server/lib/provider-api.js";
+import {
+  createPipelineDashboardConfig,
+  crmPipelineDashboardId,
+  CRM_PIPELINE_PROGRAM_CODE,
+  CRM_PIPELINE_PROGRAM_COLUMNS,
+  CRM_PIPELINE_PROGRAM_NAME,
+  CRM_PIPELINE_PROGRAM_TITLE,
+  CRM_PIPELINE_REFRESH_TTL_MS,
+  CRM_PIPELINE_DASHBOARD_TITLE,
+  requireDashboardAccess,
+} from "./_crm-dashboard.js";
+import getCrmPipelineData from "./get-crm-pipeline-data.js";
+
+export default defineAction({
+  description:
+    "Install or update your CRM Pipeline dashboard and its owned data program. Safe to rerun: it verifies the access-scoped source first, upserts the program by owner and name, then revision-writes the dashboard.",
+  schema: z.object({}),
+  run: async (_args, ctx?: ActionRunContext) => {
+    const access = requireDashboardAccess(ctx);
+    const preview = await getCrmPipelineData.run({}, ctx);
+
+    const program = await upsertDataProgram({
+      appId: CRM_APP_ID,
+      name: CRM_PIPELINE_PROGRAM_NAME,
+      title: CRM_PIPELINE_PROGRAM_TITLE,
+      description:
+        "Access-scoped opportunity totals by stage for the CRM Pipeline dashboard.",
+      code: CRM_PIPELINE_PROGRAM_CODE,
+      outputColumns: JSON.stringify(CRM_PIPELINE_PROGRAM_COLUMNS),
+      refreshMode: "ttl",
+      refreshTtlMs: CRM_PIPELINE_REFRESH_TTL_MS,
+      background: false,
+      ownerEmail: access.userEmail,
+      orgId: access.orgId ?? null,
+    });
+    if (
+      program.appId !== CRM_APP_ID ||
+      program.name !== CRM_PIPELINE_PROGRAM_NAME
+    ) {
+      throw new Error(
+        "CRM Pipeline data program could not be verified after saving.",
+      );
+    }
+
+    const dashboardId = crmPipelineDashboardId(access);
+    const existing = await crmDashboardStore.get(dashboardId, access);
+    const dashboard = await crmDashboardStore.write(
+      {
+        id: dashboardId,
+        kind: "pipeline",
+        title: CRM_PIPELINE_DASHBOARD_TITLE,
+        config: createPipelineDashboardConfig(program.id),
+        ...(existing ? { expectedUpdatedAt: existing.updatedAt } : {}),
+      },
+      access,
+    );
+    if (dashboard.config.panels.length !== 3) {
+      throw new Error(
+        "CRM Pipeline dashboard could not be verified after saving.",
+      );
+    }
+
+    return {
+      dashboard,
+      dashboardId: dashboard.id,
+      programId: program.id,
+      created: !existing,
+      programPreview: {
+        rowCount: preview.rows.length,
+        columns: CRM_PIPELINE_PROGRAM_COLUMNS,
+        truncated: preview.truncated,
+      },
+    };
+  },
+});

package/corpus/templates/crm/actions/list-crm-attributes.ts

@@ -0,0 +1,71 @@
+import { defineAction } 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 { queryFlag } from "./_crm-action-utils.js";
+import {
+  loadAttributeOptions,
+  toAttributeDefinition,
+} from "./_crm-attribute-utils.js";
+
+export default defineAction({
+  description:
+    "List the typed attributes (schema) of one CRM object type or list, with their managed status/select options. Use this before reading, writing, filtering, or grouping record values so slugs, types, cardinality, and option values are exact. Archived attributes are excluded unless includeArchived is set.",
+  schema: z.object({
+    target: z.enum(["object", "list"]).default("object"),
+    targetId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(200)
+      .describe(
+        "The object type for target=object (for example accounts), or the list id for target=list.",
+      ),
+    connectionId: z.string().trim().min(1).max(128).optional(),
+    includeArchived: queryFlag,
+    limit: z.coerce.number().int().min(1).max(500).default(200),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const rows = await getDb()
+      .select()
+      .from(schema.crmFieldPolicies)
+      .where(
+        and(
+          eq(schema.crmFieldPolicies.target, args.target),
+          // `object_type` carries the target for both kinds — for list
+          // attributes it mirrors `target_id` — and, unlike `target_id`, it is
+          // populated on rows written by the provider adapters.
+          eq(schema.crmFieldPolicies.objectType, args.targetId),
+          ...(args.connectionId
+            ? [eq(schema.crmFieldPolicies.connectionId, args.connectionId)]
+            : []),
+          ...(args.includeArchived
+            ? []
+            : [eq(schema.crmFieldPolicies.archived, false)]),
+          accessFilter(schema.crmFieldPolicies, schema.crmFieldPolicyShares),
+        ),
+      )
+      .orderBy(
+        asc(schema.crmFieldPolicies.position),
+        asc(schema.crmFieldPolicies.label),
+      )
+      .limit(args.limit);
+
+    const options = await loadAttributeOptions({
+      attributeIds: rows.map((row) => row.id),
+      includeArchived: args.includeArchived,
+    });
+
+    return {
+      target: args.target,
+      targetId: args.targetId,
+      attributes: rows.map((row) =>
+        toAttributeDefinition(row, options.get(row.id) ?? []),
+      ),
+    };
+  },
+});

package/corpus/templates/crm/actions/list-crm-connections.ts

@@ -0,0 +1,68 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { desc } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+/**
+ * The object types a connection mirrors. An unreadable blob is not reported as
+ * "mirrors nothing": the settings UI would then render an empty target picker,
+ * which is indistinguishable from a correctly configured CRM that happens to
+ * have no objects.
+ */
+function parseObjectTypes(connectionId: string, raw: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `CRM connection ${connectionId} has an unreadable selected_object_types_json. Repair it before reading this connection.`,
+    );
+  }
+  if (
+    !Array.isArray(parsed) ||
+    parsed.some((value) => typeof value !== "string")
+  ) {
+    throw new Error(
+      `CRM connection ${connectionId} has a selected_object_types_json that is not a list of object types.`,
+    );
+  }
+  return parsed as string[];
+}
+
+export default defineAction({
+  description:
+    "List the access-scoped CRM connections with their mode, health, and mirrored object types. Use it to discover which object types a connection carries before reading or authoring attributes on them. The mode `hybrid` is deprecated and only ever appears on connections configured before per-attribute authority replaced it.",
+  schema: z.object({
+    limit: z.coerce.number().int().min(1).max(50).default(20),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const rows = await getDb()
+      .select({
+        id: schema.crmConnections.id,
+        provider: schema.crmConnections.provider,
+        label: schema.crmConnections.label,
+        accountId: schema.crmConnections.accountId,
+        mode: schema.crmConnections.mode,
+        status: schema.crmConnections.status,
+        selectedObjectTypesJson: schema.crmConnections.selectedObjectTypesJson,
+        lastSyncedAt: schema.crmConnections.lastSyncedAt,
+        lastError: schema.crmConnections.lastError,
+        updatedAt: schema.crmConnections.updatedAt,
+      })
+      .from(schema.crmConnections)
+      .where(accessFilter(schema.crmConnections, schema.crmConnectionShares))
+      .orderBy(desc(schema.crmConnections.updatedAt))
+      .limit(args.limit);
+
+    return {
+      connections: rows.map(({ selectedObjectTypesJson, ...row }) => ({
+        ...row,
+        objectTypes: parseObjectTypes(row.id, selectedObjectTypesJson),
+      })),
+    };
+  },
+});

package/corpus/templates/crm/actions/list-crm-dashboard-revisions.ts

@@ -0,0 +1,15 @@
+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:
+    "List the bounded revision history for one access-scoped CRM dashboard.",
+  schema: z.object({ id: z.string().trim().min(1).max(200) }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: ({ id }, ctx?: ActionRunContext) =>
+    crmDashboardStore.listRevisions(id, requireDashboardAccess(ctx)),
+});

package/corpus/templates/crm/actions/list-crm-dashboards.ts

@@ -0,0 +1,15 @@
+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:
+    "List up to 50 active CRM dashboards the current user can access.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (_args, ctx?: ActionRunContext) =>
+    (await crmDashboardStore.list(requireDashboardAccess(ctx))).slice(0, 50),
+});

package/corpus/templates/crm/actions/list-crm-enrichment-slots.ts

@@ -0,0 +1,28 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  CRM_ENRICHMENT_SLOT_UNIT_COST,
+  resolveEnrichmentBudgetUnits,
+} from "../server/lib/enrichment-cost.js";
+import { describeEnrichmentSlots } from "../server/lib/enrichment-slots.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+
+export default defineAction({
+  description:
+    "List the CRM enrichment slots with their credential state and unit price. A slot is a capability (company, person, contact, web, calls), not a vendor — which provider backs a slot is an internal binding and never appears here. Each slot reports credential.status as granted, missing (with a reason), or unknown (the lookup itself failed, which is NOT the same as missing). Slots in the verify phase are free-standing evidence gathering; the spend phase slots carry contact data and are the ones the approval gate protects. Call this before estimate-crm-enrichment to see which slots a run can actually use.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (_args, ctx) => {
+    requireCrmScope(ctx);
+    const slots = await describeEnrichmentSlots();
+    return {
+      budgetUnitsPerPeriod: resolveEnrichmentBudgetUnits(),
+      slots: slots.map((slot) => ({
+        ...slot,
+        unitCost: CRM_ENRICHMENT_SLOT_UNIT_COST[slot.slot],
+      })),
+    };
+  },
+});