@agent-native/core 0.123.0 → 0.123.1

package/corpus/templates/crm/actions/list-crm-record-values.ts

@@ -0,0 +1,200 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq, inArray, isNull } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { storageColumnFor } from "../shared/crm-attributes.js";
+import type { CrmValue } from "../shared/crm-contract.js";
+import {
+  CrmAttributeValueError,
+  loadAttributeOptions,
+  toAttributeDefinition,
+  type CrmAttributeRow,
+} from "./_crm-attribute-utils.js";
+
+const MAX_RECORDS = 200;
+
+interface StoredValueRow {
+  stringValue: string | null;
+  numberValue: number | null;
+  booleanValue: boolean | null;
+  jsonValue: string | null;
+}
+
+/**
+ * Decode by the attribute's declared storage column, never by sniffing which
+ * column is non-null: a `false` checkbox and an empty text field are otherwise
+ * indistinguishable.
+ */
+function decodeValue(
+  attribute: CrmAttributeRow,
+  row: StoredValueRow,
+): CrmValue {
+  const column = storageColumnFor(attribute.attributeType, attribute.multi);
+  if (column === "numberValue") return row.numberValue;
+  if (column === "booleanValue") return row.booleanValue;
+  if (column === "jsonValue") {
+    if (row.jsonValue === null) return null;
+    try {
+      return JSON.parse(row.jsonValue) as CrmValue;
+    } catch {
+      throw new CrmAttributeValueError(
+        "crm-attribute-value-unreadable",
+        `Stored value for "${attribute.apiSlug ?? attribute.fieldName}" is not readable JSON. It was written outside the attribute writer.`,
+      );
+    }
+  }
+  return row.stringValue;
+}
+
+export default defineAction({
+  description:
+    "Return the current typed attribute values for a bounded set of CRM records, with each value's actor and provenance blob and each record's current revision. This is the value payload behind the record grid: list-crm-records returns row summaries, this returns the cells. Only current values are returned (the bitemporal row whose activeUntil is null); list-entry values are excluded.",
+  schema: z.object({
+    recordIds: z
+      .array(z.string().trim().min(1).max(128))
+      .min(1)
+      .max(MAX_RECORDS)
+      .describe("Local CRM record IDs from list-crm-records."),
+    includeArchived: z
+      .boolean()
+      .default(false)
+      .describe("Include values of archived attributes."),
+  }),
+  readOnly: true,
+  run: async (args) => {
+    const db = getDb();
+    const recordIds = [...new Set(args.recordIds)];
+    const records = await db
+      .select({
+        id: schema.crmRecords.id,
+        connectionId: schema.crmRecords.connectionId,
+        objectType: schema.crmRecords.objectType,
+        provider: schema.crmRecords.provider,
+        remoteRevision: schema.crmRecords.remoteRevision,
+      })
+      .from(schema.crmRecords)
+      .where(
+        and(
+          inArray(schema.crmRecords.id, recordIds),
+          eq(schema.crmRecords.tombstone, false),
+          accessFilter(schema.crmRecords, schema.crmRecordShares),
+        ),
+      );
+    if (records.length === 0) {
+      return { records: [], attributes: [] };
+    }
+
+    const objectTypes = [...new Set(records.map((row) => row.objectType))];
+    const connectionIds = [...new Set(records.map((row) => row.connectionId))];
+    const attributeRows = await db
+      .select()
+      .from(schema.crmFieldPolicies)
+      .where(
+        and(
+          eq(schema.crmFieldPolicies.target, "object"),
+          inArray(schema.crmFieldPolicies.objectType, objectTypes),
+          inArray(schema.crmFieldPolicies.connectionId, connectionIds),
+          ...(args.includeArchived
+            ? []
+            : [eq(schema.crmFieldPolicies.archived, false)]),
+          accessFilter(schema.crmFieldPolicies, schema.crmFieldPolicyShares),
+        ),
+      );
+    const options = await loadAttributeOptions({
+      attributeIds: attributeRows.map((row) => row.id),
+      includeArchived: args.includeArchived,
+    });
+    // Keyed by field_name: that is the column the bitemporal writer keys on and
+    // the value `api_slug` was seeded from.
+    const attributeByKey = new Map(
+      attributeRows.map((row) => [
+        `${row.connectionId}:${row.objectType}:${row.fieldName}`,
+        row,
+      ]),
+    );
+
+    const valueRows = await db
+      .select({
+        recordId: schema.crmRecordFields.recordId,
+        fieldName: schema.crmRecordFields.fieldName,
+        stringValue: schema.crmRecordFields.stringValue,
+        numberValue: schema.crmRecordFields.numberValue,
+        booleanValue: schema.crmRecordFields.booleanValue,
+        jsonValue: schema.crmRecordFields.jsonValue,
+        activeFrom: schema.crmRecordFields.activeFrom,
+        actorType: schema.crmRecordFields.actorType,
+        actorId: schema.crmRecordFields.actorId,
+        provenanceJson: schema.crmRecordFields.provenanceJson,
+      })
+      .from(schema.crmRecordFields)
+      .where(
+        and(
+          inArray(schema.crmRecordFields.recordId, recordIds),
+          // A list-entry value lives in this same table; `entry_id IS NULL` is
+          // the record-vs-entry discriminator.
+          isNull(schema.crmRecordFields.entryId),
+          isNull(schema.crmRecordFields.activeUntil),
+          accessFilter(schema.crmRecordFields, schema.crmRecordFieldShares),
+        ),
+      );
+
+    const recordById = new Map(records.map((row) => [row.id, row]));
+    const buckets = new Map<
+      string,
+      {
+        values: Record<string, CrmValue>;
+        valuesSince: Record<string, string>;
+        provenance: Record<
+          string,
+          { actorType: string; actorId: string | null; provenanceJson: string }
+        >;
+      }
+    >(
+      records.map((row) => [
+        row.id,
+        { values: {}, valuesSince: {}, provenance: {} },
+      ]),
+    );
+
+    for (const row of valueRows) {
+      const record = recordById.get(row.recordId);
+      const bucket = buckets.get(row.recordId);
+      if (!record || !bucket) continue;
+      const attribute = attributeByKey.get(
+        `${record.connectionId}:${record.objectType}:${row.fieldName}`,
+      );
+      // A value with no surviving attribute definition is not a cell the grid
+      // can type; skipping it here is not data loss — the row is still stored.
+      if (!attribute) continue;
+      const slug = attribute.apiSlug ?? attribute.fieldName;
+      bucket.values[slug] = decodeValue(attribute, row);
+      bucket.valuesSince[slug] = row.activeFrom;
+      bucket.provenance[slug] = {
+        actorType: row.actorType,
+        actorId: row.actorId,
+        provenanceJson: row.provenanceJson,
+      };
+    }
+
+    return {
+      attributes: attributeRows.map((row) =>
+        toAttributeDefinition(row, options.get(row.id) ?? []),
+      ),
+      records: records.map((row) => {
+        const bucket = buckets.get(row.id)!;
+        return {
+          recordId: row.id,
+          connectionId: row.connectionId,
+          objectType: row.objectType,
+          provider: row.provider,
+          remoteRevision: row.remoteRevision,
+          values: bucket.values,
+          valuesSince: bucket.valuesSince,
+          provenance: bucket.provenance,
+        };
+      }),
+    };
+  },
+});

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

@@ -0,0 +1,103 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import {
+  createConnectedCrmAdapter,
+  isConnectedCrmProvider,
+} from "../server/crm/adapter.js";
+import { resolveNativeCrmAccessScope } from "../server/crm/native-adapter.js";
+import {
+  crmFilterSchema,
+  crmSortSchema,
+  queryCrmRecords,
+} from "../server/lib/crm-query.js";
+
+const kinds = [
+  "account",
+  "person",
+  "opportunity",
+  "activity",
+  "task",
+  "custom",
+] as const;
+
+export default defineAction({
+  description:
+    'List a bounded, access-scoped page of CRM records. Filters, sorting, and pagination all run in SQL: pass a typed filter tree (or a saved viewId whose filter is used), an ordered sort, and the cursor from the previous page. A condition value of "@currentUser" resolves to the calling user on actor-reference attributes and owner fields. A filter naming an unknown or archived attribute fails rather than returning unfiltered rows.',
+  schema: z.object({
+    kind: z
+      .enum(kinds)
+      .optional()
+      .describe("Optional canonical CRM record kind."),
+    connectionId: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("Optional CRM connection ID."),
+    viewId: z
+      .string()
+      .min(1)
+      .max(128)
+      .optional()
+      .describe(
+        "Optional access-scoped saved CRM view ID; its stored filter, sort, and columns are applied. Cannot be combined with filter.",
+      ),
+    query: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .optional()
+      .describe("Optional display-name search, ANDed on top of the filter."),
+    filter: crmFilterSchema
+      .optional()
+      .describe(
+        'Typed filter tree: {op:"and"|"or", conditions:[{attributeId|field, condition, value}]}, nestable one level. Date values accept the relative tokens today, this-week, last-N-days, and next-N-days.',
+      ),
+    sort: crmSortSchema
+      .optional()
+      .describe(
+        "Ordered sort keys; record id breaks ties so pagination cannot skip or repeat a row.",
+      ),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z
+      .string()
+      .max(4_000)
+      .optional()
+      .describe("Cursor returned by a previous page of this same query."),
+    includeTotal: z
+      .boolean()
+      .optional()
+      .describe(
+        "Include totalEstimate: the filtered row count before per-record provider scope revalidation.",
+      ),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: (input, ctx?: ActionRunContext) =>
+    queryCrmRecords(input, {
+      actorEmail: ctx?.userEmail ?? getRequestUserEmail() ?? null,
+      resolveScope: async (target) => {
+        if (target.provider === "native") {
+          return resolveNativeCrmAccessScope({
+            connectionId: target.connectionId,
+            objectType: target.objectType,
+          });
+        }
+        if (
+          !isConnectedCrmProvider(target.provider) ||
+          !target.workspaceConnectionId
+        ) {
+          return null;
+        }
+        const adapter = await createConnectedCrmAdapter({
+          provider: target.provider,
+          connectionId: target.workspaceConnectionId,
+          ...(ctx?.userEmail ? { userEmail: ctx.userEmail } : {}),
+          ...(ctx?.orgId !== undefined ? { orgId: ctx.orgId } : {}),
+        });
+        return adapter.getAccessScope(target.objectType);
+      },
+    }),
+});

package/corpus/templates/crm/actions/list-crm-saved-views.ts

@@ -0,0 +1,66 @@
+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 { hydrateSavedViewRow } from "../server/lib/crm-query.js";
+
+export default defineAction({
+  description:
+    "List access-scoped saved CRM views with their stored filter, sort, columns, board grouping, audience, and optional linked data-program ID.",
+  schema: z.object({
+    viewKind: z.enum(["table", "board"]).optional(),
+    targetKind: z.enum(["object", "list"]).optional(),
+    targetId: z.string().trim().min(1).max(128).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (input) => {
+    const conditions = [
+      accessFilter(schema.crmSavedViews, schema.crmSavedViewShares),
+    ];
+    if (input.viewKind) {
+      conditions.push(eq(schema.crmSavedViews.viewKind, input.viewKind));
+    }
+    if (input.targetKind) {
+      conditions.push(eq(schema.crmSavedViews.targetKind, input.targetKind));
+    }
+    if (input.targetId) {
+      conditions.push(eq(schema.crmSavedViews.targetId, input.targetId));
+    }
+    const rows = await getDb()
+      .select()
+      .from(schema.crmSavedViews)
+      .where(and(...conditions))
+      .orderBy(
+        desc(schema.crmSavedViews.pinned),
+        desc(schema.crmSavedViews.updatedAt),
+      )
+      .limit(input.limit);
+
+    return {
+      views: rows.map((row) => {
+        const view = hydrateSavedViewRow(row);
+        return {
+          id: view.id,
+          name: view.name,
+          description: view.description || undefined,
+          kind: view.kind ?? undefined,
+          viewKind: view.viewKind,
+          targetKind: view.targetKind,
+          targetId: view.targetId ?? undefined,
+          groupByAttributeId: view.groupByAttributeId ?? undefined,
+          filters: view.filter,
+          sort: view.sort,
+          columns: view.columns,
+          dataProgramId: view.dataProgramId ?? undefined,
+          pinned: view.pinned,
+          audience: view.audience,
+          updatedAt: view.updatedAt,
+        };
+      }),
+    };
+  },
+});

package/corpus/templates/crm/actions/list-crm-signal-hits.ts

@@ -0,0 +1,43 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, desc, eq, like, or } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+export default defineAction({
+  description:
+    "List bounded, access-scoped CRM signals. Results contain evidence references and short excerpts, never transcripts or media.",
+  schema: z.object({
+    recordId: z.string().trim().min(1).max(128).optional(),
+    reviewStatus: z.enum(["unreviewed", "confirmed", "dismissed"]).optional(),
+    query: z.string().trim().max(120).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const filters = [accessFilter(schema.crmSignals, schema.crmSignalShares)];
+    if (args.recordId)
+      filters.push(eq(schema.crmSignals.recordId, args.recordId));
+    if (args.reviewStatus)
+      filters.push(eq(schema.crmSignals.reviewStatus, args.reviewStatus));
+    if (args.query) {
+      const escaped = args.query.replace(/[\\%_]/g, "\\$&");
+      filters.push(
+        or(
+          like(schema.crmSignals.label, `%${escaped}%`),
+          like(schema.crmSignals.quote, `%${escaped}%`),
+          like(schema.crmSignals.summary, `%${escaped}%`),
+        )!,
+      );
+    }
+    const signals = await getDb()
+      .select()
+      .from(schema.crmSignals)
+      .where(and(...filters))
+      .orderBy(desc(schema.crmSignals.createdAt))
+      .limit(args.limit);
+    return { signals };
+  },
+});

package/corpus/templates/crm/actions/list-crm-signal-trackers.ts

@@ -0,0 +1,32 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { asc } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { DEFAULT_CRM_DETECTORS } from "../server/lib/intelligence/default-detectors.js";
+
+export default defineAction({
+  description:
+    "List access-scoped CRM signal detectors and the safe default pack when none are configured.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async () => {
+    const rows = await getDb()
+      .select()
+      .from(schema.crmSignalTrackers)
+      .where(
+        accessFilter(schema.crmSignalTrackers, schema.crmSignalTrackerShares),
+      )
+      .orderBy(asc(schema.crmSignalTrackers.name));
+    return {
+      trackers: rows.map((row) => ({
+        ...row,
+        keywords: JSON.parse(row.keywordsJson) as string[],
+        keywordsJson: undefined,
+      })),
+      suggestedDefaults: rows.length ? [] : DEFAULT_CRM_DETECTORS,
+    };
+  },
+});

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

@@ -0,0 +1,22 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { listCrmTasks } from "../server/db/crm-store.js";
+
+export default defineAction({
+  description:
+    "List a bounded, access-scoped page of CRM follow-up tasks. Filter by the linked record or task status when needed.",
+  schema: z.object({
+    recordId: z.string().min(1).optional(),
+    status: z.enum(["open", "done", "cancelled"]).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z
+      .string()
+      .regex(/^\d+$/)
+      .optional()
+      .describe("Cursor returned by a previous page."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: (input) => listCrmTasks(input),
+});

package/corpus/templates/crm/actions/list-staged-datasets.ts

@@ -0,0 +1,14 @@
+import { createListStagedDatasetsAction } from "@agent-native/core/provider-api/actions/staged-datasets";
+import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+import { CRM_APP_ID } from "../server/lib/provider-api.js";
+
+export default createListStagedDatasetsAction({
+  description:
+    "List caller-scoped staged CRM provider datasets created by provider-api-request. Use a dataset id with query-staged-dataset to reduce a result, or delete-staged-dataset after analysis.",
+  schema: z.object({}),
+  appId: CRM_APP_ID,
+  getOwnerEmail: () => getCredentialContext()?.userEmail ?? null,
+  http: { method: "GET" },
+});

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

@@ -0,0 +1,47 @@
+import { defineAction } from "@agent-native/core/action";
+import { listWorkspaceConnectionsForApp } from "@agent-native/core/workspace-connections";
+import { z } from "zod";
+
+import { CRM_APP_ID } from "../server/lib/provider-api.js";
+
+const httpBoolean = z.preprocess((value) => {
+  if (typeof value !== "string") return value;
+  if (["true", "1"].includes(value.toLowerCase())) return true;
+  if (["false", "0"].includes(value.toLowerCase())) return false;
+  return value;
+}, z.boolean());
+
+export default defineAction({
+  description:
+    "List safe metadata for HubSpot and Salesforce workspace connections currently granted to CRM. Provider credentials and credential references are never returned.",
+  schema: z.object({
+    includeDisabled: httpBoolean.default(false),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ includeDisabled }) => {
+    const connectionGroups = await Promise.all(
+      (["hubspot", "salesforce"] as const).map((provider) =>
+        listWorkspaceConnectionsForApp({
+          appId: CRM_APP_ID,
+          provider,
+          includeDisabled,
+        }),
+      ),
+    );
+    const connections = connectionGroups.flat();
+    return {
+      connections: connections.map((connection) => ({
+        id: connection.id,
+        provider: connection.provider,
+        label: connection.label,
+        accountId: connection.accountId,
+        accountLabel: connection.accountLabel,
+        status: connection.status,
+        lastCheckedAt: connection.lastCheckedAt,
+        lastUsedAt: connection.lastUsedAt,
+        accessMode: connection.appAccess.mode,
+      })),
+    };
+  },
+});