@agent-native/core 0.114.15 → 0.115.1

package/corpus/templates/crm/actions/attach-call-evidence.ts

@@ -0,0 +1,170 @@
+import { defineAction } from "@agent-native/core/action";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq, inArray } from "drizzle-orm";
+import { z } from "zod";
+
+import { isSafeCrmEvidenceExcerpt } from "../server/crm/crm-field-firewall.js";
+import { getDb, schema } from "../server/db/index.js";
+import { isDurableClipsEvidenceUrl } from "../shared/crm-automation-recipes.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+
+const httpsUrl = z
+  .string()
+  .url()
+  .max(2_048)
+  .refine(
+    (value) => /^https:\/\//i.test(value),
+    "sourceUrl must be an https URL",
+  );
+
+export default defineAction({
+  description:
+    "Attach bounded call evidence to a CRM record. Store only an artifact reference, URL, optional short quote, speaker, timestamp, and summary; never submit a transcript or media payload.",
+  schema: z
+    .object({
+      recordId: z.string().trim().min(1).max(128).optional(),
+      recordIds: z
+        .array(z.string().trim().min(1).max(128))
+        .min(1)
+        .max(20)
+        .optional(),
+      interactionId: z.string().trim().min(1).max(128).optional(),
+      artifactId: z.string().trim().min(1).max(256),
+      sourceUrl: httpsUrl,
+      sourceApp: z.string().trim().min(1).max(80).default("clips"),
+      artifactType: z.string().trim().min(1).max(80).default("call-evidence"),
+      quote: z
+        .string()
+        .trim()
+        .max(1_200)
+        .refine(
+          isSafeCrmEvidenceExcerpt,
+          "quote must be a bounded human-readable excerpt, not transcript, media, binary, base64, or data-url content",
+        )
+        .optional(),
+      speaker: z.string().trim().max(240).optional(),
+      startSeconds: z.number().finite().min(0).max(86_400).optional(),
+      endSeconds: z.number().finite().min(0).max(86_400).optional(),
+      summary: z
+        .string()
+        .trim()
+        .max(2_000)
+        .refine(
+          isSafeCrmEvidenceExcerpt,
+          "summary must be a bounded human-readable excerpt, not transcript, media, binary, base64, or data-url content",
+        )
+        .optional(),
+      capturedAt: z.string().datetime({ offset: true }).optional(),
+    })
+    .superRefine((value, issue) => {
+      if (
+        (!value.recordId && !value.recordIds) ||
+        (value.recordId && value.recordIds)
+      ) {
+        issue.addIssue({
+          code: "custom",
+          message: "Provide exactly one of recordId or recordIds",
+          path: ["recordId"],
+        });
+      }
+      if (
+        value.endSeconds !== undefined &&
+        value.startSeconds !== undefined &&
+        value.endSeconds < value.startSeconds
+      ) {
+        issue.addIssue({
+          code: "custom",
+          message: "endSeconds must be after startSeconds",
+          path: ["endSeconds"],
+        });
+      }
+      if (
+        value.sourceApp.trim().toLowerCase() === "clips" &&
+        !isDurableClipsEvidenceUrl(value.sourceUrl)
+      ) {
+        issue.addIssue({
+          code: "custom",
+          message:
+            "Clips evidence must use a durable /share/<id> or /r/<id> page URL without an access token, media endpoint, or transcript fragment",
+          path: ["sourceUrl"],
+        });
+      }
+    }),
+  audit: {
+    target: (args, result) => {
+      const value = result as {
+        evidence?: Array<{
+          ownerEmail: string;
+          orgId: string | null;
+          visibility: "private" | "org";
+        }>;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      const evidence = value.evidence?.[0] ?? value;
+      return {
+        type: "crm-record",
+        id: args.recordId ?? args.recordIds?.[0] ?? "unknown",
+        ownerEmail: evidence.ownerEmail,
+        orgId: evidence.orgId,
+        visibility: evidence.visibility,
+      };
+    },
+    summary: (args) =>
+      `Attached call evidence to ${args.recordIds?.length ?? 1} CRM record${args.recordIds?.length === 1 ? "" : "s"}`,
+    recordInputs: false,
+  },
+  run: async (args, ctx) => {
+    const recordIds = args.recordId
+      ? [args.recordId]
+      : [...new Set(args.recordIds ?? [])];
+    await Promise.all(
+      recordIds.map((recordId) =>
+        assertAccess("crm-record", recordId, "editor"),
+      ),
+    );
+    if (args.interactionId)
+      await assertAccess("crm-interaction", args.interactionId, "viewer");
+    const db = getDb();
+    const scope = requireCrmScope(ctx);
+    const now = new Date().toISOString();
+    const rows = recordIds.map((recordId) => ({
+      id: crypto.randomUUID(),
+      interactionId: args.interactionId ?? null,
+      recordId,
+      sourceApp: args.sourceApp,
+      artifactType: args.artifactType,
+      artifactId: args.artifactId,
+      sourceUrl: args.sourceUrl,
+      quote: args.quote ?? "",
+      speaker: args.speaker ?? null,
+      startSeconds: args.startSeconds ?? null,
+      endSeconds: args.endSeconds ?? null,
+      summary: args.summary ?? "",
+      capturedAt: args.capturedAt ?? now,
+      ...scope,
+      createdAt: now,
+      updatedAt: now,
+    }));
+    await db.transaction(async (tx) => {
+      await tx.insert(schema.crmCallEvidence).values(rows);
+    });
+    const evidence = await db
+      .select()
+      .from(schema.crmCallEvidence)
+      .where(
+        and(
+          inArray(
+            schema.crmCallEvidence.id,
+            rows.map((row) => row.id),
+          ),
+          eq(schema.crmCallEvidence.ownerEmail, scope.ownerEmail),
+        ),
+      )
+      .limit(recordIds.length);
+    if (evidence.length !== recordIds.length)
+      throw new Error("Call evidence could not be verified after saving.");
+    return args.recordId ? evidence[0] : { evidence };
+  },
+});

package/corpus/templates/crm/actions/configure-crm-connection.ts

@@ -0,0 +1,126 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { createConnectedCrmAdapter } from "../server/crm/adapter.js";
+import { getDb, schema } from "../server/db/index.js";
+import { requireCrmScope, toJson } from "./_crm-action-utils.js";
+
+const idList = z.array(z.string().trim().min(1).max(160)).max(50).default([]);
+
+export default defineAction({
+  description:
+    "Register an authorized HubSpot or Salesforce workspace Connection as a scoped CRM companion connection. Provider credentials remain in workspace Connections.",
+  schema: z.object({
+    provider: z.enum(["hubspot", "salesforce"]).default("hubspot"),
+    workspaceConnectionId: z.string().trim().min(1).max(160).optional(),
+    label: z.string().trim().min(1).max(160).optional(),
+    mode: z.enum(["connected", "hybrid"]).default("connected"),
+    selectedPipelineIds: idList,
+    selectedObjectTypes: z
+      .array(z.string().trim().min(1).max(120))
+      .min(1)
+      .max(50)
+      .optional(),
+  }),
+  audit: {
+    target: (_args, result) => {
+      const connection = result as {
+        id: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-connection",
+        id: connection.id,
+        ownerEmail: connection.ownerEmail,
+        orgId: connection.orgId,
+        visibility: connection.visibility,
+      };
+    },
+    summary: (_args, result) =>
+      `Configured CRM connection ${(result as { id?: string })?.id ?? ""}`,
+    recordInputs: false,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    const scope = requireCrmScope(ctx);
+    const adapter = await createConnectedCrmAdapter({
+      provider: args.provider,
+      connectionId: args.workspaceConnectionId,
+      userEmail: scope.ownerEmail,
+      orgId: scope.orgId,
+    });
+    const id = adapter.connection.connectionId;
+    const db = getDb();
+    const [existing] = await db
+      .select({ id: schema.crmConnections.id })
+      .from(schema.crmConnections)
+      .where(
+        and(
+          eq(schema.crmConnections.workspaceConnectionId, id),
+          accessFilter(schema.crmConnections, schema.crmConnectionShares),
+        ),
+      )
+      .limit(1);
+    const now = new Date().toISOString();
+    const selectedObjectTypes =
+      args.selectedObjectTypes ??
+      (args.provider === "hubspot"
+        ? ["companies", "contacts", "deals"]
+        : ["Account", "Contact", "Opportunity"]);
+    const accessScopeKey = `workspace:${id}:${adapter.connection.actorId ?? scope.ownerEmail}`;
+    const values = {
+      provider: args.provider,
+      workspaceConnectionId: id,
+      label:
+        args.label ?? (args.provider === "hubspot" ? "HubSpot" : "Salesforce"),
+      accountId: adapter.connection.accountId ?? null,
+      mode: args.mode,
+      status: "connected" as const,
+      selectedPipelinesJson: toJson(args.selectedPipelineIds, 8_000),
+      selectedObjectTypesJson: toJson(selectedObjectTypes, 8_000),
+      accessScopeKey,
+      accessScopeJson: toJson(
+        {
+          key: accessScopeKey,
+          actorId: adapter.connection.actorId,
+          mode: adapter.connection.actorId ? "user" : "service-account",
+          recordVisibility: adapter.connection.actorId ? "actor" : "unknown",
+        },
+        4_000,
+      ),
+      lastError: null,
+      updatedAt: now,
+    };
+    const localId = existing?.id ?? id;
+
+    if (existing) {
+      await assertAccess("crm-connection", existing.id, "editor");
+      await db
+        .update(schema.crmConnections)
+        .set(values)
+        .where(
+          and(
+            eq(schema.crmConnections.id, existing.id),
+            accessFilter(
+              schema.crmConnections,
+              schema.crmConnectionShares,
+              undefined,
+              "editor",
+            ),
+          ),
+        );
+    } else {
+      await db.insert(schema.crmConnections).values({
+        id: localId,
+        ...values,
+        ...scope,
+        createdAt: now,
+      });
+    }
+
+    return { id: localId, ...scope, provider: args.provider };
+  },
+});

package/corpus/templates/crm/actions/configure-native-crm.ts

@@ -0,0 +1,44 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { configureNativeCrmConnection } from "../server/crm/native-adapter.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+
+export default defineAction({
+  description:
+    "Initialize a local-authoritative Native SQL CRM with accounts, people, and opportunities. It requires no provider connection or credential and uses the configured SQLite, Postgres, or D1 database.",
+  schema: z.object({
+    label: z.string().trim().min(1).max(160).optional(),
+  }),
+  audit: {
+    target: (_args, result) => {
+      const connection = result as {
+        id: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-connection",
+        id: connection.id,
+        ownerEmail: connection.ownerEmail,
+        orgId: connection.orgId,
+        visibility: connection.visibility,
+      };
+    },
+    summary: (_args, result) =>
+      `Configured Native SQL CRM ${(result as { id?: string })?.id ?? ""}`,
+    recordInputs: false,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    const result = await configureNativeCrmConnection({
+      label: args.label,
+      ownership: requireCrmScope(ctx),
+    });
+    return {
+      ...result,
+      provider: "native" as const,
+      mode: "native" as const,
+    };
+  },
+});

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

@@ -0,0 +1,148 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import {
+  configureNativeCrmConnection,
+  createNativeCrmAdapter,
+} from "../server/crm/native-adapter.js";
+import { getDb, schema } from "../server/db/index.js";
+import type { CrmValue } from "../shared/crm-contract.js";
+import {
+  crmInitiatedBy,
+  isSafeCrmMutationFields,
+  MAX_CRM_FIELDS_PER_MUTATION,
+  requireCrmScope,
+  scopedCrmIdempotencyKey,
+} from "./_crm-action-utils.js";
+
+const kindToObjectType = {
+  account: "accounts",
+  person: "people",
+  opportunity: "opportunities",
+} as const;
+
+export const nativeRecordFieldsSchema = z
+  .record(z.string().trim().min(1).max(120), z.unknown())
+  .refine(
+    (fields) => Object.keys(fields).length <= MAX_CRM_FIELDS_PER_MUTATION,
+    `Provide at most ${MAX_CRM_FIELDS_PER_MUTATION} fields.`,
+  )
+  .refine(
+    isSafeCrmMutationFields,
+    "CRM fields and values cannot contain media, transcripts, data URLs, base64, or oversized JSON.",
+  );
+
+export default defineAction({
+  description:
+    "Create an account, person, or opportunity in Native SQL CRM. The record is local-authoritative, access-scoped, idempotent, audited, and has no upstream provider write.",
+  schema: z.object({
+    connectionId: z.string().trim().min(1).max(128).optional(),
+    kind: z.enum(["account", "person", "opportunity"]),
+    displayName: z.string().trim().min(1).max(500),
+    fields: nativeRecordFieldsSchema.optional(),
+    idempotencyKey: z.string().trim().min(1).max(256).optional(),
+  }),
+  audit: {
+    target: (_args, result) => {
+      const record = result as {
+        recordId: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-record",
+        id: record.recordId,
+        ownerEmail: record.ownerEmail,
+        orgId: record.orgId,
+        visibility: record.visibility,
+      };
+    },
+    summary: (args) =>
+      `Created Native SQL CRM ${args.kind} ${args.displayName}`,
+    recordInputs: false,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    const ownership = requireCrmScope(ctx);
+    const db = getDb();
+    const connectionRows = await db
+      .select({ id: schema.crmConnections.id })
+      .from(schema.crmConnections)
+      .where(
+        and(
+          eq(schema.crmConnections.provider, "native"),
+          ...(args.connectionId
+            ? [eq(schema.crmConnections.id, args.connectionId)]
+            : []),
+          accessFilter(
+            schema.crmConnections,
+            schema.crmConnectionShares,
+            undefined,
+            "editor",
+          ),
+        ),
+      )
+      .limit(args.connectionId ? 1 : 2);
+    if (!connectionRows.length && args.connectionId) {
+      throw new Error(
+        "The selected Native SQL CRM is unavailable or you do not have editor access.",
+      );
+    }
+    if (!args.connectionId && connectionRows.length > 1) {
+      throw new Error(
+        "More than one Native SQL CRM is available. Provide connectionId to choose one.",
+      );
+    }
+    const connectionId =
+      connectionRows[0]?.id ??
+      (
+        await configureNativeCrmConnection({
+          ownership,
+        })
+      ).id;
+    const objectType = kindToObjectType[args.kind];
+    const remoteId = crypto.randomUUID();
+    const fields = {
+      ...(args.fields as Record<string, CrmValue> | undefined),
+      displayName: args.displayName,
+      ...(args.kind === "person" ? {} : { name: args.displayName }),
+    };
+    const idempotencyKey = await scopedCrmIdempotencyKey({
+      ...ownership,
+      recordId: `${connectionId}:${objectType}`,
+      key: args.idempotencyKey ?? crypto.randomUUID(),
+    });
+    const adapter = await createNativeCrmAdapter({
+      connectionId,
+      initiatedBy: crmInitiatedBy(ctx),
+    });
+    const result = await adapter.applyMutation({
+      operation: "create",
+      record: {
+        connectionId,
+        provider: "native",
+        objectType,
+        kind: args.kind,
+        remoteId,
+      },
+      fields,
+      idempotencyKey,
+    });
+    if (result.status !== "applied" || !result.record?.ref.localId) {
+      throw new Error(
+        result.message ?? "Native SQL CRM record was not created.",
+      );
+    }
+    return {
+      recordId: result.record.ref.localId,
+      connectionId,
+      provider: "native" as const,
+      kind: args.kind,
+      displayName: result.record.displayName,
+      revision: result.remoteRevision,
+      ...ownership,
+    };
+  },
+});

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

@@ -0,0 +1,58 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+
+export default defineAction({
+  description:
+    "Create a bounded keyword or delegated-agent CRM signal detector. Smart detectors define criteria only; this action never calls a model.",
+  schema: z
+    .object({
+      name: z.string().trim().min(1).max(120),
+      description: z.string().trim().max(500).default(""),
+      kind: z.enum(["keyword", "smart"]),
+      keywords: z.array(z.string().trim().min(1).max(80)).max(40).default([]),
+      classifierPrompt: z.string().trim().max(1_000).default(""),
+      enabled: z.boolean().default(true),
+    })
+    .superRefine((value, ctx) => {
+      if (value.kind === "keyword" && value.keywords.length === 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["keywords"],
+          message: "Keyword detectors require at least one keyword.",
+        });
+      }
+      if (value.kind === "smart" && !value.classifierPrompt) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["classifierPrompt"],
+          message: "Smart detectors require a classification criterion.",
+        });
+      }
+    }),
+  run: async (args, ctx) => {
+    const scope = requireCrmScope(ctx);
+    const now = new Date().toISOString();
+    const id = crypto.randomUUID();
+    await getDb()
+      .insert(schema.crmSignalTrackers)
+      .values({
+        id,
+        name: args.name,
+        description: args.description,
+        kind: args.kind,
+        keywordsJson: JSON.stringify(
+          args.kind === "keyword" ? args.keywords : [],
+        ),
+        classifierPrompt: args.kind === "smart" ? args.classifierPrompt : "",
+        enabled: args.enabled,
+        isDefault: false,
+        ...scope,
+        createdAt: now,
+        updatedAt: now,
+      });
+    return { id, ...args };
+  },
+});

package/corpus/templates/crm/actions/delete-staged-dataset.ts

@@ -0,0 +1,14 @@
+import { createDeleteStagedDatasetAction } 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 createDeleteStagedDatasetAction({
+  description:
+    "Delete a caller-scoped staged dataset after CRM analysis is complete.",
+  schema: z.object({ datasetId: z.string().min(1) }),
+  appId: CRM_APP_ID,
+  getOwnerEmail: () => getCredentialContext()?.userEmail ?? null,
+  http: false,
+});

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,33 @@
+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";
+
+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.");
+    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(),
+});