@agent-native/core 0.123.0 → 0.123.2

package/corpus/templates/crm/actions/_crm-signal-utils.ts

@@ -0,0 +1,79 @@
+import type { ActionRunContext } from "@agent-native/core/action";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq, inArray } from "drizzle-orm";
+
+import { getDb, schema } from "../server/db/index.js";
+import type { CallEvidenceExcerpt } from "../server/lib/intelligence/evidence.js";
+import {
+  requireCrmScope,
+  scopedCrmIdempotencyKey,
+} from "./_crm-action-utils.js";
+
+export async function loadCrmSignalEvidence(args: {
+  recordId: string;
+  evidenceIds?: string[];
+  role?: "viewer" | "editor";
+}) {
+  await assertAccess("crm-record", args.recordId, args.role ?? "viewer");
+  const db = getDb();
+  const predicates = [
+    eq(schema.crmCallEvidence.recordId, args.recordId),
+    accessFilter(schema.crmCallEvidence, schema.crmCallEvidenceShares),
+  ];
+  if (args.evidenceIds?.length) {
+    predicates.push(inArray(schema.crmCallEvidence.id, args.evidenceIds));
+  }
+  const rows = await db
+    .select()
+    .from(schema.crmCallEvidence)
+    .where(and(...predicates))
+    .limit(20);
+  if (
+    args.evidenceIds?.length &&
+    rows.length !== new Set(args.evidenceIds).size
+  ) {
+    throw new Error("One or more call-evidence references are unavailable.");
+  }
+  return rows;
+}
+
+export function evidenceExcerpts(
+  rows: Awaited<ReturnType<typeof loadCrmSignalEvidence>>,
+): CallEvidenceExcerpt[] {
+  return rows.flatMap((row) => {
+    const quote = row.quote.trim() || row.summary.trim();
+    if (!quote) return [];
+    return [
+      {
+        evidenceRef: row.id,
+        quote,
+        ...(row.speaker ? { speaker: row.speaker } : {}),
+        startSeconds: row.startSeconds ?? 0,
+        ...(row.endSeconds !== null ? { endSeconds: row.endSeconds } : {}),
+      },
+    ];
+  });
+}
+
+export async function crmSignalIdempotencyKey(
+  ctx: ActionRunContext | undefined,
+  recordId: string,
+  key: string,
+) {
+  const scope = requireCrmScope(ctx);
+  return {
+    scope,
+    key: await scopedCrmIdempotencyKey({
+      ownerEmail: scope.ownerEmail,
+      orgId: scope.orgId,
+      recordId,
+      key: `signal:${key}`,
+    }),
+  };
+}
+
+export function signalTupleError(message: string): never {
+  const error = new Error(message) as Error & { statusCode?: number };
+  error.statusCode = 404;
+  throw error;
+}

package/corpus/templates/crm/actions/add-crm-record-to-list.ts

@@ -0,0 +1,164 @@
+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 {
+  isSafeCrmMutationFields,
+  MAX_CRM_FIELDS_PER_MUTATION,
+  requireCrmScope,
+} from "./_crm-action-utils.js";
+import {
+  CrmListError,
+  crmActorFrom,
+  indexAttributes,
+  loadCrmListAttributes,
+  requireCrmList,
+  writeCrmListEntryValues,
+} from "./_crm-list-utils.js";
+
+export const listEntryValuesSchema = z
+  .record(z.string().trim().min(1).max(120), z.unknown())
+  .refine(
+    (values) => Object.keys(values).length <= MAX_CRM_FIELDS_PER_MUTATION,
+    `Provide at most ${MAX_CRM_FIELDS_PER_MUTATION} entry attributes.`,
+  )
+  .refine(
+    isSafeCrmMutationFields,
+    "CRM entry values cannot contain media, transcripts, data URLs, base64, or oversized JSON.",
+  );
+
+export default defineAction({
+  description:
+    "Add a record to a CRM list as a new entry, with optional starting values for the list's own entry attributes. A record may hold more than one entry in the same list — two open deals for one company are two entries — so this never de-duplicates; it returns existingEntryIds for the caller to decide. The record's objectType must match the list's parentObjectType. The entry is local-authoritative even when the record mirrors HubSpot or Salesforce.",
+  schema: z.object({
+    listId: z.string().trim().min(1).max(128),
+    recordId: z.string().trim().min(1).max(128),
+    values: listEntryValuesSchema.optional(),
+    position: z.number().int().min(0).max(100_000).optional(),
+  }),
+  audit: {
+    target: (_args, result) => {
+      const entry = result as {
+        entryId: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-list-entry",
+        id: entry.entryId,
+        ownerEmail: entry.ownerEmail,
+        orgId: entry.orgId,
+        visibility: entry.visibility,
+      };
+    },
+    summary: (args) =>
+      `Added CRM record ${args.recordId} to list ${args.listId}`,
+    recordInputs: false,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    const ownership = requireCrmScope(ctx);
+    const db = getDb();
+    const list = await requireCrmList(db, args.listId, "editor");
+
+    const [record] = await db
+      .select({
+        id: schema.crmRecords.id,
+        objectType: schema.crmRecords.objectType,
+        displayName: schema.crmRecords.displayName,
+      })
+      .from(schema.crmRecords)
+      .where(
+        and(
+          eq(schema.crmRecords.id, args.recordId),
+          eq(schema.crmRecords.tombstone, false),
+          accessFilter(schema.crmRecords, schema.crmRecordShares),
+        ),
+      )
+      .limit(1);
+    if (!record) {
+      throw new CrmListError(
+        "crm-record-not-found",
+        `CRM record "${args.recordId}" was not found or is not visible to you.`,
+      );
+    }
+    if (record.objectType !== list.parentObjectType) {
+      throw new CrmListError(
+        "crm-list-object-type-mismatch",
+        `List "${list.name}" holds ${list.parentObjectType}; record ${record.id} is ${record.objectType}.`,
+      );
+    }
+
+    const existing = await db
+      .select({ id: schema.crmListEntries.id })
+      .from(schema.crmListEntries)
+      .where(
+        and(
+          eq(schema.crmListEntries.listId, list.id),
+          eq(schema.crmListEntries.recordId, record.id),
+          accessFilter(schema.crmListEntries, schema.crmListEntryShares),
+        ),
+      )
+      .limit(50);
+
+    const attributes = indexAttributes(
+      await loadCrmListAttributes(db, list.id),
+    );
+    const [last] = await db
+      .select({ position: schema.crmListEntries.position })
+      .from(schema.crmListEntries)
+      .where(
+        and(
+          eq(schema.crmListEntries.listId, list.id),
+          accessFilter(schema.crmListEntries, schema.crmListEntryShares),
+        ),
+      )
+      .orderBy(desc(schema.crmListEntries.position))
+      .limit(1);
+
+    const entryId = crypto.randomUUID();
+    const actor = crmActorFrom(ctx);
+    const now = new Date().toISOString();
+
+    // One transaction so a rejected value (an unknown status option, say) can
+    // never leave a half-populated entry behind.
+    const writes = await db.transaction(async (tx) => {
+      await tx.insert(schema.crmListEntries).values({
+        id: entryId,
+        listId: list.id,
+        recordId: record.id,
+        position: args.position ?? (last ? last.position + 1 : 0),
+        createdByActorType: actor.type,
+        createdByActorId: actor.id,
+        ...ownership,
+        createdAt: now,
+        updatedAt: now,
+      });
+      return writeCrmListEntryValues({
+        db: tx,
+        recordId: record.id,
+        entryId,
+        attributes,
+        values: args.values ?? {},
+        actor,
+        ownership,
+        now,
+      });
+    });
+
+    return {
+      entryId,
+      listId: list.id,
+      recordId: record.id,
+      /**
+       * Entries this record already had in this list. Non-empty is normal, not
+       * an error — the caller decides whether a second entry was intended.
+       */
+      existingEntryIds: existing.map((entry) => entry.id),
+      values: writes,
+      ...ownership,
+    };
+  },
+});

package/corpus/templates/crm/actions/apply-crm-proposals.ts

@@ -0,0 +1,291 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq, inArray, isNull } from "drizzle-orm";
+import { z } from "zod";
+
+import { isConnectedCrmProvider } from "../server/crm/adapter.js";
+import {
+  resolveProviderRecordLink,
+  type ProviderRecordLink,
+} from "../server/crm/provider-record-link.js";
+import { getDb, schema } from "../server/db/index.js";
+import {
+  isSafeCrmMutationFields,
+  parseJsonRecord,
+  requireCrmScope,
+} from "./_crm-action-utils.js";
+
+const PROVIDER_LABELS = {
+  hubspot: "HubSpot",
+  salesforce: "Salesforce",
+} as const;
+
+/**
+ * A prepared field change. `beforeKnown` separates "the mirror holds no value
+ * for this field" from "the mirrored value is empty" — collapsing them would
+ * show a confident `— → Renewal` diff for a field we simply do not mirror.
+ */
+interface PreparedField {
+  name: string;
+  beforeKnown: boolean;
+  before: string | number | boolean | null;
+  after: unknown;
+}
+
+function updateAffectedRows(result: unknown): number {
+  if (!result || typeof result !== "object") return 0;
+  const value = result as {
+    rowsAffected?: unknown;
+    rowCount?: unknown;
+    count?: unknown;
+    changes?: unknown;
+    meta?: { changes?: unknown };
+  };
+  for (const count of [
+    value.rowsAffected,
+    value.rowCount,
+    value.count,
+    value.changes,
+    value.meta?.changes,
+  ]) {
+    if (typeof count === "number") return count;
+  }
+  return 0;
+}
+
+function currentMirroredValue(row: {
+  stringValue: string | null;
+  numberValue: number | null;
+  booleanValue: boolean | null;
+  jsonValue: string | null;
+}): string | number | boolean | null {
+  if (row.stringValue !== null) return row.stringValue;
+  if (row.numberValue !== null) return row.numberValue;
+  if (row.booleanValue !== null) return row.booleanValue;
+  return row.jsonValue;
+}
+
+export default defineAction({
+  description:
+    "Prepare one pending HubSpot or Salesforce record change for completion upstream. Returns the exact before/after diff and a deep link to the record, and records the handoff in the proposal ledger. It never writes to the provider and never reports an upstream change as applied.",
+  schema: z.object({
+    proposalId: z.string().trim().min(1).max(128),
+  }),
+  needsApproval: true,
+  audit: {
+    target: (_args, result) => {
+      const response = result as {
+        recordId: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-record",
+        id: response.recordId,
+        ownerEmail: response.ownerEmail,
+        orgId: response.orgId,
+        visibility: response.visibility,
+      };
+    },
+    summary: (args) =>
+      `Prepared CRM proposal ${args.proposalId} for upstream completion`,
+    recordInputs: false,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    await assertAccess("crm-mutation", args.proposalId, "editor");
+    const db = getDb();
+    const [proposal] = await db
+      .select()
+      .from(schema.crmMutations)
+      .where(
+        and(
+          eq(schema.crmMutations.id, args.proposalId),
+          accessFilter(
+            schema.crmMutations,
+            schema.crmMutationShares,
+            undefined,
+            "editor",
+          ),
+        ),
+      )
+      .limit(1);
+    if (!proposal) throw new Error("CRM proposal was not found.");
+    if (proposal.target !== "provider" || proposal.operation !== "update") {
+      throw new Error(
+        "Only pending provider update proposals can be prepared in this phase.",
+      );
+    }
+    if (proposal.status !== "pending") {
+      throw new Error(
+        `CRM proposal is ${proposal.status} and cannot be prepared again.`,
+      );
+    }
+    if (!proposal.recordId || !proposal.connectionId) {
+      throw new Error(
+        "CRM proposal is missing its record or connection reference.",
+      );
+    }
+    await assertAccess("crm-record", proposal.recordId, "editor");
+    await assertAccess("crm-connection", proposal.connectionId, "editor");
+    const [[record], [connection]] = await Promise.all([
+      db
+        .select()
+        .from(schema.crmRecords)
+        .where(
+          and(
+            eq(schema.crmRecords.id, proposal.recordId),
+            accessFilter(
+              schema.crmRecords,
+              schema.crmRecordShares,
+              undefined,
+              "editor",
+            ),
+          ),
+        )
+        .limit(1),
+      db
+        .select()
+        .from(schema.crmConnections)
+        .where(
+          and(
+            eq(schema.crmConnections.id, proposal.connectionId),
+            accessFilter(
+              schema.crmConnections,
+              schema.crmConnectionShares,
+              undefined,
+              "editor",
+            ),
+          ),
+        )
+        .limit(1),
+    ]);
+    if (!record || record.tombstone || !connection) {
+      throw new Error(
+        "CRM proposal no longer has an available record and connection.",
+      );
+    }
+    if (!isConnectedCrmProvider(connection.provider)) {
+      throw new Error(
+        "Only HubSpot and Salesforce provider proposals are enabled in this release.",
+      );
+    }
+    if (!connection.workspaceConnectionId) {
+      throw new Error(
+        "CRM connection is missing its workspace connection reference.",
+      );
+    }
+    // Without a revision anchor the mirrored "before" column cannot be trusted
+    // to describe the record the user is about to edit by hand.
+    if (!proposal.expectedRemoteRevision) {
+      throw new Error(
+        "CRM proposal has no remote revision and must be recreated from a refreshed record.",
+      );
+    }
+    const patch = parseJsonRecord(proposal.patchJson);
+    const fields = patch.fields;
+    if (!fields || typeof fields !== "object" || Array.isArray(fields)) {
+      throw new Error("CRM proposal has an invalid field patch.");
+    }
+    const fieldPatch = fields as Record<string, unknown>;
+    if (!isSafeCrmMutationFields(fieldPatch)) {
+      throw new Error("CRM proposal contains an unsafe field patch.");
+    }
+    const fieldNames = Object.keys(fieldPatch);
+
+    const currentRows = fieldNames.length
+      ? await db
+          .select({
+            fieldName: schema.crmRecordFields.fieldName,
+            stringValue: schema.crmRecordFields.stringValue,
+            numberValue: schema.crmRecordFields.numberValue,
+            booleanValue: schema.crmRecordFields.booleanValue,
+            jsonValue: schema.crmRecordFields.jsonValue,
+          })
+          .from(schema.crmRecordFields)
+          .where(
+            and(
+              eq(schema.crmRecordFields.recordId, record.id),
+              isNull(schema.crmRecordFields.entryId),
+              isNull(schema.crmRecordFields.activeUntil),
+              inArray(schema.crmRecordFields.fieldName, fieldNames),
+              accessFilter(schema.crmRecordFields, schema.crmRecordFieldShares),
+            ),
+          )
+      : [];
+    const currentByFieldName = new Map(
+      currentRows.map((row) => [row.fieldName, row]),
+    );
+    const preparedFields: PreparedField[] = fieldNames.map((name) => {
+      const current = currentByFieldName.get(name);
+      return {
+        name,
+        beforeKnown: Boolean(current),
+        before: current ? currentMirroredValue(current) : null,
+        after: fieldPatch[name],
+      };
+    });
+
+    const link: ProviderRecordLink = await resolveProviderRecordLink({
+      provider: connection.provider,
+      objectType: record.objectType,
+      remoteId: record.remoteId,
+      accountId: connection.accountId,
+      workspaceConnectionId: connection.workspaceConnectionId,
+    });
+
+    const scope = requireCrmScope(ctx);
+    const now = new Date().toISOString();
+    // `approved` with `appliedAt` still null is the ledger's "prepared and
+    // handed off, never written upstream" state. `error` stays null so a
+    // working handoff is never mistaken for a failure.
+    const claim = await db
+      .update(schema.crmMutations)
+      .set({
+        status: "approved",
+        approvedBy: scope.ownerEmail,
+        approvedAt: now,
+        error: null,
+        updatedAt: now,
+      })
+      .where(
+        and(
+          eq(schema.crmMutations.id, proposal.id),
+          eq(schema.crmMutations.status, "pending"),
+          accessFilter(
+            schema.crmMutations,
+            schema.crmMutationShares,
+            undefined,
+            "editor",
+          ),
+        ),
+      );
+    if (updateAffectedRows(claim) !== 1) {
+      throw new Error(
+        "CRM proposal was already claimed by another preparation attempt.",
+      );
+    }
+
+    const providerLabel = PROVIDER_LABELS[connection.provider];
+    return {
+      proposalId: proposal.id,
+      recordId: record.id,
+      recordName: record.displayName,
+      status: "approved" as const,
+      /** This release never completes a provider write. Always false. */
+      upstreamApplied: false,
+      provider: connection.provider,
+      providerLabel,
+      preparedAt: now,
+      fields: preparedFields,
+      recordUrl: link.available ? link.url : null,
+      recordUrlUnavailableReason: link.available ? null : link.reason,
+      guidance: link.available
+        ? `Reviewed and ready. Open the record in ${providerLabel} and make this change there — CRM has not written it upstream.`
+        : `Reviewed and ready. CRM could not build a ${providerLabel} record link (${link.reason}); find the record in ${providerLabel} and make this change there. CRM has not written it upstream.`,
+      ownerEmail: record.ownerEmail,
+      orgId: record.orgId,
+      visibility: record.visibility,
+    };
+  },
+});

package/corpus/templates/crm/actions/archive-crm-attribute.ts

@@ -0,0 +1,69 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, count, eq, isNull } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  loadAttributeOptions,
+  requireEditableAttribute,
+  toAttributeDefinition,
+} from "./_crm-attribute-utils.js";
+
+export default defineAction({
+  description:
+    "Archive one CRM attribute. This is a soft archive: the attribute stops appearing in the grid and pickers, and every stored value and history row it owns is retained untouched. Attributes are never deleted. Use update-crm-attribute with archived=false to restore one.",
+  schema: z.object({
+    attributeId: z.string().trim().min(1).max(128),
+  }),
+  audit: {
+    target: (args) => ({ type: "crm-field-policy", id: args.attributeId }),
+    summary: (args) => `Archived CRM attribute ${args.attributeId}`,
+  },
+  run: async (args) => {
+    const current = await requireEditableAttribute(args.attributeId);
+    const db = getDb();
+
+    if (!current.archived) {
+      await db
+        .update(schema.crmFieldPolicies)
+        .set({ archived: true, updatedAt: new Date().toISOString() })
+        .where(eq(schema.crmFieldPolicies.id, args.attributeId));
+    }
+
+    // Reported so a caller can see the archive kept data rather than removed it.
+    const [values] = await db
+      .select({ total: count() })
+      .from(schema.crmRecordFields)
+      .where(
+        and(
+          eq(schema.crmRecordFields.attributeId, args.attributeId),
+          isNull(schema.crmRecordFields.activeUntil),
+          accessFilter(schema.crmRecordFields, schema.crmRecordFieldShares),
+        ),
+      );
+
+    if (!values) {
+      throw new Error(
+        "Retained CRM attribute values could not be counted; the archive was not confirmed.",
+      );
+    }
+
+    const [row] = await db
+      .select()
+      .from(schema.crmFieldPolicies)
+      .where(eq(schema.crmFieldPolicies.id, args.attributeId))
+      .limit(1);
+    if (!row) {
+      throw new Error("CRM attribute could not be verified after archiving.");
+    }
+    const options = await loadAttributeOptions({
+      attributeIds: [row.id],
+      includeArchived: true,
+    });
+    return {
+      ...toAttributeDefinition(row, options.get(row.id) ?? []),
+      retainedValueCount: values.total,
+    };
+  },
+});