@agent-native/core 0.114.16 → 0.115.1

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,
+    };
+  },
+});

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

@@ -0,0 +1,75 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  createConnectedCrmAdapter,
+  isConnectedCrmProvider,
+} from "../server/crm/adapter.js";
+import { createNativeCrmAdapter } from "../server/crm/native-adapter.js";
+import { loadVerifiedReadThroughRecord } from "../server/crm/read-through.js";
+import {
+  getCrmRecord,
+  getCrmRecordReadContext,
+  getReadThroughRelationshipSummaries,
+} from "../server/db/crm-store.js";
+
+export default defineAction({
+  description:
+    "Return one access-scoped CRM record with bounded mirrored fields, recent interaction metadata, call-evidence references, and tasks. It never returns raw provider payloads, media, or transcripts.",
+  schema: z.object({
+    recordId: z.string().min(1).describe("Local CRM record ID."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ recordId }, ctx?: ActionRunContext) => {
+    const context = await getCrmRecordReadContext(recordId);
+    if (!context) {
+      const error = new Error("CRM record not found") as Error & {
+        statusCode?: number;
+      };
+      error.statusCode = 404;
+      throw error;
+    }
+    const adapter =
+      context.provider === "native"
+        ? await createNativeCrmAdapter({
+            connectionId: context.connectionId,
+            accessTier: "viewer",
+          })
+        : isConnectedCrmProvider(context.provider) &&
+            context.workspaceConnectionId
+          ? await createConnectedCrmAdapter({
+              provider: context.provider,
+              connectionId: context.workspaceConnectionId,
+              ...(ctx?.userEmail ? { userEmail: ctx.userEmail } : {}),
+              ...(ctx?.orgId !== undefined ? { orgId: ctx.orgId } : {}),
+            })
+          : null;
+    if (!adapter) {
+      throw new Error("CRM access cannot be verified for this record.");
+    }
+    const readThrough = await loadVerifiedReadThroughRecord({
+      adapter,
+      context,
+    });
+    const relatedRecords = await getReadThroughRelationshipSummaries({
+      context,
+      relationships: readThrough.relationships,
+      currentScopes: readThrough.currentScopes,
+    });
+    const record = await getCrmRecord(recordId, {
+      displayName: readThrough.remote.displayName,
+      fields: readThrough.remote.fields,
+      remoteRevision: readThrough.remote.remoteRevision,
+      remoteUpdatedAt: readThrough.remote.remoteUpdatedAt,
+      relatedRecords,
+      accessScope: readThrough.currentScope,
+    });
+    if (record) return record;
+    const error = new Error("CRM record not found") as Error & {
+      statusCode?: number;
+    };
+    error.statusCode = 404;
+    throw error;
+  },
+});

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-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-proposals.ts

@@ -0,0 +1,31 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { listCrmProposals } from "../server/db/crm-store.js";
+
+export default defineAction({
+  description:
+    "List bounded, access-scoped CRM mutation proposals and their review status. Proposal payloads are intentionally omitted from this list surface.",
+  schema: z.object({
+    recordId: z.string().min(1).optional(),
+    status: z
+      .enum([
+        "pending",
+        "approved",
+        "applied",
+        "rejected",
+        "conflict",
+        "failed",
+      ])
+      .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) => listCrmProposals(input),
+});

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

@@ -0,0 +1,79 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  createConnectedCrmAdapter,
+  isConnectedCrmProvider,
+} from "../server/crm/adapter.js";
+import { resolveNativeCrmAccessScope } from "../server/crm/native-adapter.js";
+import { listCrmRecords } from "../server/db/crm-store.js";
+
+const kinds = [
+  "account",
+  "person",
+  "opportunity",
+  "activity",
+  "task",
+  "custom",
+] as const;
+
+export default defineAction({
+  description:
+    "List a bounded, access-scoped page of thinly mirrored CRM records. Use kind, connectionId, or a short display-name query to narrow the scope; remote-only and redacted fields are excluded.",
+  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."),
+    query: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .optional()
+      .describe("Optional display-name search."),
+    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, ctx?: ActionRunContext) =>
+    listCrmRecords(input, {
+      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,15 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { listCrmSavedViews } from "../server/db/crm-store.js";
+
+export default defineAction({
+  description:
+    "List access-scoped saved CRM views, including their optional linked data-program IDs.",
+  schema: z.object({
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: (input) => listCrmSavedViews(input),
+});

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,
+      })),
+    };
+  },
+});

package/corpus/templates/crm/actions/manage-crm-signal-tracker.ts

@@ -0,0 +1,87 @@
+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";
+
+const inputSchema = z
+  .object({
+    trackerId: z.string().trim().min(1).max(128),
+    operation: z.enum(["set-enabled", "delete"]),
+    enabled: z.boolean().optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.operation === "set-enabled" && value.enabled === undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["enabled"],
+        message: "enabled is required when changing a tracker state.",
+      });
+    }
+    if (value.operation === "delete" && value.enabled !== undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["enabled"],
+        message: "enabled cannot be provided when deleting a tracker.",
+      });
+    }
+  });
+
+export default defineAction({
+  description:
+    "Enable, disable, or delete one access-scoped local CRM signal tracker. This never invokes a model or changes a connected provider.",
+  schema: inputSchema,
+  audit: {
+    target: (_args, result) => {
+      const tracker = result as {
+        id: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-signal-tracker",
+        id: tracker.id,
+        ownerEmail: tracker.ownerEmail,
+        orgId: tracker.orgId,
+        visibility: tracker.visibility,
+      };
+    },
+    summary: (args) =>
+      args.operation === "delete"
+        ? `Deleted CRM signal tracker ${args.trackerId}`
+        : `${args.enabled ? "Enabled" : "Disabled"} CRM signal tracker ${args.trackerId}`,
+  },
+  run: async (args) => {
+    await assertAccess("crm-signal-tracker", args.trackerId, "editor");
+    const db = getDb();
+    const [tracker] = await db
+      .select()
+      .from(schema.crmSignalTrackers)
+      .where(eq(schema.crmSignalTrackers.id, args.trackerId))
+      .limit(1);
+    if (!tracker) throw new Error("CRM signal tracker was not found.");
+
+    if (args.operation === "delete") {
+      await db
+        .delete(schema.crmSignalTrackers)
+        .where(eq(schema.crmSignalTrackers.id, args.trackerId));
+      return { ...tracker, deleted: true };
+    }
+
+    const now = new Date().toISOString();
+    await db
+      .update(schema.crmSignalTrackers)
+      .set({ enabled: args.enabled!, updatedAt: now })
+      .where(eq(schema.crmSignalTrackers.id, args.trackerId));
+    const [updated] = await db
+      .select()
+      .from(schema.crmSignalTrackers)
+      .where(eq(schema.crmSignalTrackers.id, args.trackerId))
+      .limit(1);
+    if (!updated)
+      throw new Error("CRM signal tracker could not be verified after saving.");
+    return updated;
+  },
+});