@agent-native/core 0.114.16 → 0.115.3

package/corpus/templates/crm/README.md

@@ -0,0 +1,106 @@
+# CRM
+
+CRM is an agent-native CRM that runs either as a standalone Native SQL system
+or as a scoped companion for connected HubSpot and Salesforce workspaces. It
+provides fast record work, saved views, tasks, cadence, evidence, reviewable
+call signals, and agent workflows without forcing a provider choice.
+
+Native SQL is local-authoritative and portable across SQLite, Postgres, and D1.
+The connected modes support scoped Connected and Hybrid behavior: HubSpot maps
+companies, contacts, and deals; Salesforce maps Accounts, Contacts, and
+Opportunities.
+
+## Guardrails
+
+- Native SQL requires no external connection or provider credential.
+- Provider credentials are workspace Connections only.
+- The mirror contains configured cohorts and allow-listed fields, not raw
+  provider exports.
+- Sensitive fields default to redacted and unknown fields are remote-only.
+- Evidence stores a bounded quote and source reference, never transcripts or
+  media.
+- Signal detectors produce timestamped evidence citations. Keyword matching is
+  local; smart moments and summaries are delegated through agent chat and saved
+  only after grounding validation.
+- Provider mutations are revision-aware, audited, and proposed when agent risk
+  requires approval.
+
+## Start or connect CRM
+
+1. Open **Set up CRM** and select **Start with Native SQL** to use CRM without
+   HubSpot or Salesforce. Native records and fields are local-authoritative.
+2. To use CRM as a companion, in shared **Settings → Connections**, authorize
+   HubSpot or Salesforce and
+   grant the connection to CRM. OAuth and refresh tokens stay in workspace
+   Connections; CRM never accepts a token or key. Salesforce production is the
+   default. For a sandbox, use **Authorize the sandbox directly** on Set up CRM;
+   the selected login environment is retained for token refresh.
+3. Choose the granted connection and select a recent
+   history window. HubSpot may be narrowed to deal pipeline IDs; Salesforce
+   starts with recently updated Accounts, Contacts, and Opportunities.
+4. CRM mirrors the selected cohort and allow-listed fields only. Confirm the
+   connection actor's access before relying on a record in the local mirror.
+
+## Operating model
+
+- **Connected**: the source CRM is authoritative. CRM is a scoped companion
+  for record work, saved views, tasks, call evidence, and analysis.
+- **Hybrid**: the source CRM remains authoritative for remote fields; CRM may
+  own explicitly configured derived-local and local-authoritative fields.
+- **Native SQL**: CRM is the system of record for its accounts, people,
+  opportunities, relationships, saved views, tasks, cadence, and local fields.
+  It has no upstream provider, sync job, or provider token.
+- **Signals**: attach one Clips call-evidence artifact to one or more CRM
+  records, run the default Pricing, Competitors, Objections, Next steps,
+  Budget, and Timing detectors, then confirm or dismiss the grounded results.
+  Clips remains the owner of recording, transcript, consent, and media access.
+- **Clips review recipe**: from a chosen CRM record, prepare a default-off
+  `clip.created` recipe. After explicit activation, its Clips-owned trigger
+  ignores the event media URL, resolves the clip through an access-checked
+  read action, and attaches only its opaque ID, durable HTTPS `/r/<id>` page,
+  and capture time to that exact CRM record. It never copies media or a
+  transcript, infers another record, or authorizes a provider write.
+- **Pipeline dashboard**: install the CRM-owned Pipeline dashboard to get
+  action-backed stage, amount, and close-date panels. Its data program and
+  dashboard revisions are access-scoped CRM records; the reusable chart and
+  table presentation comes from the Toolkit dashboard kit.
+- **Read and write safety**: provider reads use the connection's effective
+  permissions. Upstream changes are revision-aware, access-checked proposals
+  in this release; finish the approved change in HubSpot or Salesforce and do
+  not claim a provider write completed from CRM.
+
+## Review and delegation policy
+
+CRM records the actor, expected remote revision, idempotency key, field-level
+provenance, and an audit event for each mutation request. Local, reversible
+routine work can execute in CRM. Agent-initiated provider changes become
+reviewable proposals; destructive, bulk, and named-risk changes remain gated.
+Delegated authority is narrow and stored as policy—it never expands record or
+field access, bypasses the write firewall, or turns a provider result into an
+unverified success.
+
+Salesforce reads are validated against the current connection actor and field
+permissions before mirrored data is returned. A service-account mirror never
+proves a user's access; ambiguous or changed access fails closed until refresh.
+
+## Live testing
+
+Use a shared, already-authorized workspace Connection—never copy its secret
+into an environment file. Choose a small recent cohort, verify the resulting
+records and access scope in CRM, then test a proposal without applying a
+provider change. Record only connection labels, counts, and non-sensitive
+results in test evidence.
+
+See [the CRM contract](docs/architecture/crm-contract.md) for field policies,
+identity, access scope, and write decisions.
+
+## Local development
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Set `DATABASE_URL` for persistent deployment storage. Native SQL works without
+external credentials. Connect HubSpot or Salesforce from the workspace
+Connections surface; do not add provider secrets to `.env`.

package/corpus/templates/crm/_gitignore

@@ -0,0 +1,12 @@
+node_modules
+dist
+build
+.output
+.netlify
+.react-router
+.generated
+data/*.db
+data/*.db-shm
+data/*.db-wal
+.env
+.env.local

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

@@ -0,0 +1,87 @@
+import type { ActionRunContext } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+
+export {
+  isBoundedCrmValue,
+  isSafeCrmMutationFieldName,
+  isSafeCrmMutationFields,
+} from "../server/crm/crm-field-firewall.js";
+
+export const MAX_CRM_FIELDS_PER_MUTATION = 20;
+
+export function requireCrmScope(ctx?: ActionRunContext) {
+  const ownerEmail = ctx?.userEmail ?? getRequestUserEmail();
+  if (!ownerEmail) throw new Error("Sign in is required to manage CRM data.");
+  const orgId = ctx?.orgId ?? getRequestOrgId() ?? null;
+  return {
+    ownerEmail,
+    orgId,
+    visibility: orgId ? ("org" as const) : ("private" as const),
+  };
+}
+
+export function crmInitiatedBy(ctx?: ActionRunContext) {
+  if (ctx?.caller === "automation") return "automation" as const;
+  return ctx?.caller === "tool" ||
+    ctx?.caller === "mcp" ||
+    ctx?.caller === "a2a"
+    ? ("agent" as const)
+    : ("human" as const);
+}
+
+export function crmWriteRisk(fieldNames: string[]) {
+  const names = fieldNames.map((field) => field.toLowerCase());
+  if (names.some((field) => field.includes("owner")))
+    return "ownership" as const;
+  if (names.some((field) => field === "amount" || field.includes("amount"))) {
+    return "amount" as const;
+  }
+  if (
+    names.some((field) => field.includes("stage") || field.includes("pipeline"))
+  ) {
+    return "stage" as const;
+  }
+  return "routine" as const;
+}
+
+export async function scopedCrmIdempotencyKey(input: {
+  ownerEmail: string;
+  orgId: string | null;
+  recordId: string;
+  key: string;
+}): Promise<string> {
+  const value = [
+    "crm-mutation-v1",
+    input.ownerEmail.toLowerCase(),
+    input.orgId ?? "",
+    input.recordId,
+    input.key,
+  ].join("\u0000");
+  const bytes = new TextEncoder().encode(value);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return `crm:v1:${Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("")}`;
+}
+
+export function toJson(value: unknown, maxChars: number) {
+  const encoded = JSON.stringify(value);
+  if (encoded.length > maxChars) {
+    throw new Error(`CRM payload exceeds the ${maxChars}-character limit.`);
+  }
+  return encoded;
+}
+
+export function parseJsonRecord(value: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}

package/corpus/templates/crm/actions/_crm-dashboard.ts

@@ -0,0 +1,69 @@
+import { createHash } from "node:crypto";
+
+import type { ActionRunContext } from "@agent-native/core/action";
+import type { AccessContext } from "@agent-native/core/sharing";
+
+import type { CrmDashboardConfig } from "../server/db/index.js";
+
+export const CRM_PIPELINE_DASHBOARD_TITLE = "Pipeline";
+export const CRM_PIPELINE_PROGRAM_NAME = "crm-pipeline-by-stage";
+export const CRM_PIPELINE_PROGRAM_TITLE = "CRM pipeline by stage";
+export const CRM_PIPELINE_REFRESH_TTL_MS = 5 * 60_000;
+
+export const CRM_PIPELINE_PROGRAM_COLUMNS = [
+  { name: "stage", type: "string" },
+  { name: "pipelineValue", type: "number" },
+  { name: "opportunities", type: "number" },
+] as const;
+
+export const CRM_PIPELINE_PROGRAM_CODE = `const result = await appAction("get-crm-pipeline-data");
+emit(result.rows, ${JSON.stringify(CRM_PIPELINE_PROGRAM_COLUMNS, null, 2)});`;
+
+export function requireDashboardAccess(
+  ctx?: ActionRunContext,
+): AccessContext & { userEmail: string } {
+  const userEmail = ctx?.userEmail?.trim().toLowerCase();
+  if (!userEmail) {
+    throw new Error("CRM dashboards require an authenticated user.");
+  }
+  return { userEmail, orgId: ctx?.orgId ?? undefined };
+}
+
+export function crmPipelineDashboardId(ctx: AccessContext): string {
+  const owner = ctx.userEmail?.trim().toLowerCase();
+  if (!owner) throw new Error("CRM dashboards require an authenticated user.");
+  const scope = `${ctx.orgId ?? "personal"}:${owner}`;
+  return `crm-pipeline-${createHash("sha256").update(scope).digest("hex").slice(0, 24)}`;
+}
+
+export function createPipelineDashboardConfig(
+  programId: string,
+): CrmDashboardConfig {
+  const query = JSON.stringify({ programId });
+  return {
+    version: 1,
+    panels: [
+      {
+        id: "pipeline-total",
+        title: "Pipeline value",
+        source: "program",
+        query,
+        chartType: "metric",
+      },
+      {
+        id: "pipeline-by-stage",
+        title: "Pipeline by stage",
+        source: "program",
+        query,
+        chartType: "bar",
+      },
+      {
+        id: "pipeline-table",
+        title: "Stage detail",
+        source: "program",
+        query,
+        chartType: "table",
+      },
+    ],
+  };
+}

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/apply-crm-proposals.ts

@@ -0,0 +1,203 @@
+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 { isConnectedCrmProvider } from "../server/crm/adapter.js";
+import { getDb, schema } from "../server/db/index.js";
+import {
+  isSafeCrmMutationFields,
+  parseJsonRecord,
+  requireCrmScope,
+} from "./_crm-action-utils.js";
+
+function conditionalMutationMessage(provider: "hubspot" | "salesforce") {
+  const label = provider === "hubspot" ? "HubSpot" : "Salesforce";
+  return `${label} did not apply this update because this connection has not proved an atomic expected-revision write path. Refresh the record and make this change in ${label}.`;
+}
+
+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;
+}
+
+export default defineAction({
+  description:
+    "Review one pending HubSpot or Salesforce provider proposal. The initial release records approval and fails closed unless the connection proves an atomic expected-revision write path; otherwise make the change upstream after review.",
+  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) => `Reviewed CRM proposal ${args.proposalId}`,
+    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 reviewed in this phase.",
+      );
+    }
+    if (proposal.status !== "pending") {
+      throw new Error(
+        `CRM proposal is ${proposal.status} and cannot be reviewed.`,
+      );
+    }
+    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.",
+      );
+    }
+    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 scope = requireCrmScope(ctx);
+    const now = new Date().toISOString();
+    const message = conditionalMutationMessage(connection.provider);
+    const claim = await db
+      .update(schema.crmMutations)
+      .set({
+        status: "rejected",
+        approvedBy: scope.ownerEmail,
+        approvedAt: now,
+        error: message,
+        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 application attempt.",
+      );
+    }
+    return {
+      proposalId: proposal.id,
+      recordId: record.id,
+      status: "rejected" as const,
+      message,
+      ownerEmail: record.ownerEmail,
+      orgId: record.orgId,
+      visibility: record.visibility,
+    };
+  },
+});