@agent-native/core 0.122.4 → 0.123.1

package/corpus/templates/crm/DEVELOPING.md

@@ -0,0 +1,66 @@
+# CRM — Development Guide
+
+CRM is a React Router + Nitro Agent Native template. The UI and agent share the
+same `actions/` contract; normal client reads and writes use action hooks, not
+custom CRUD routes.
+
+## Commands
+
+- `pnpm dev` — run the local app
+- `pnpm typecheck` — run the framework typecheck
+- `pnpm test` — run unit tests
+- `pnpm build` — build the React Router and Nitro app
+
+## Architecture boundaries
+
+- `shared/crm-contract.ts` is the canonical CRM vocabulary and provider-neutral
+  contract.
+- `actions/` contains UI/agent operations. Read actions are GET; mutations use
+  the shared action surface and must preserve access checks and audit behavior.
+- `server/` owns provider adapters, scoped mirror lifecycle, and startup
+  plugins. Use a route only for protocols actions cannot model.
+- `app/` owns the persistent workspace shell and domain views. Keep normal
+  data fetching client-side through `useActionQuery` and `useActionMutation`.
+
+## Data and provider rules
+
+CRM SQL is a thin projection, not a raw HubSpot backup. Only allow-listed
+fields are mirrored; remote-only values are fetched ephemerally and redacted
+values are never fetched or exposed. Store evidence as bounded references and
+quotes only. Raw provider responses, transcripts, media, screenshots, and file
+bodies belong in their source system or approved blob storage, never SQL.
+
+Use workspace Connections for credentials. Never add provider tokens to source,
+fixtures, docs, logs, or `.env.example`. Provider API actions are the escape
+hatch for legitimate unmodeled HubSpot or Salesforce requests; stage large
+results and reduce them via data programs instead of loading an unbounded
+payload into chat.
+
+## Dashboards
+
+CRM owns its dashboard schema, revision history, access policy, data programs,
+and panel resolvers. It composes `@agent-native/toolkit/dashboard` for cards,
+tables, layout, and chart rendering only; never add fetching, provider tokens,
+or direct SQL access to Toolkit components. The Pipeline dashboard is installed
+idempotently through `install-crm-pipeline-dashboard` and reads its bounded
+opportunity data through `get-crm-pipeline-data`.
+
+`@agent-native/core/dashboard-storage` is instantiated per app. Keep CRM's
+dashboard rows and revisions scoped through its store, and use the `program`
+panel source for CRM-owned data programs. Add a provider panel source only when
+the CRM adapter can enforce the workspace connection, field policy, and access
+scope.
+
+## Signals and provider writes
+
+Call evidence is a Clips-owned artifact reference. CRM may store only bounded
+quotes, timestamps, evidence references, confidence, detector/model metadata,
+and review state; it must never store a transcript body, media, or provider
+payload. Keyword trackers run locally. Smart trackers and call summaries must
+delegate to the agent chat, then validate evidence before persisting a signal.
+
+Keep provider mutations proposal-first. `update-crm-record` records a
+revision-aware, idempotent proposal for provider-authoritative fields;
+`apply-crm-proposals` is the only path that can invoke an adapter after
+approval. Delegated policy is narrow, access-scoped, and never bypasses the
+field firewall or destructive/bulk gates.

package/corpus/templates/crm/README.md

@@ -0,0 +1,122 @@
+# CRM
+
+An agent-native CRM built around a typed, bitemporal record grid. It runs as its
+own system of record on plain SQL, or as a scoped, field-policy-aware companion
+to a connected HubSpot or Salesforce workspace — without making you pick one up
+front, and without the connected mode limiting what you can model locally.
+
+Everything the UI does, the agent does, through the same actions and the same
+SQL. `AGENTS.md` is the single source of truth for how the app behaves; the
+`crm` skill is the workflow depth behind it. This README describes the product.
+
+## What it is
+
+- **A spreadsheet grid over typed attributes.** Seventeen attribute types —
+  text, number, checkbox, currency, date, timestamp, rating, status, select,
+  record and actor references, location, domain, email, phone, and two
+  system-owned ones. Filtering, multi-key sorting, and pagination all run in
+  SQL, so a filtered page is the real result set rather than one page narrowed
+  after the fact. Keyboard navigation and TSV copy/paste work the way a
+  spreadsheet does.
+- **Every value keeps its history.** A field write closes the old row and opens
+  a new one with the actor and the time, so a record's stage history _is_ its
+  value history — no separate audit table, no "who changed this?" dead end. A
+  write that changes nothing stores nothing, so a sync does not inflate history.
+- **Lists and pipelines that are always yours.** A list is a workflow overlay
+  over one object type with its own entry attributes. Lists, entries, and entry
+  values are local-authoritative on every backend, HubSpot and Salesforce
+  included — so you can run a pipeline over connected records without needing a
+  single provider write. Time-in-stage falls out of the entry's own history.
+- **Saved views, as tables or boards.** Filter, sort, columns, and audience are
+  saved together; a board view groups by any status attribute. `@currentUser` in
+  a filter resolves per viewer, so one shared view is everyone's own pipeline.
+- **A record page, not a form.** Typed attribute panel with per-value
+  provenance, every list the record belongs to with that entry's own values, its
+  interactions and evidence, and a change history for any single value.
+- **Duplicates you can see the reason for.** Detection scores candidates on
+  email, company domain, shared root domain, and normalized name, and says which
+  one matched. Merge is explicit: you choose the survivor, values the survivor
+  lacks are promoted, both sides' entries/tasks/evidence/relationships move
+  over, and the loser is tombstoned and linked rather than deleted.
+- **Enrichment behind a two-phase spend gate.** A free verify pass gathers
+  evidence; the paid pass runs only over records a human approved, and its input
+  set is built from those approvals rather than filtered down to them. Costs are
+  estimated per line item and quoted before anything is spent, and a failed
+  provider slot is reported as a failure, never as an empty answer.
+- **Call evidence and reviewable signals.** Attach a bounded quote and source
+  reference from a Clips recording; run keyword detectors locally and delegate
+  smart moments and summaries through the agent chat. Every stored signal cites
+  an exact evidence row and waits for a human to confirm or dismiss it.
+- **Command menu and shortcuts.** ⌘K ranks records, lists, and commands
+  together, so getting anywhere is one search away rather than a click path.
+- **Admin in the app.** Settings has Connection, Fields, Lists, Intelligence,
+  and Advanced tabs — the attribute schema and its managed options are edited
+  where the data lives, not in a config file.
+
+## Modes
+
+- **Native SQL** — CRM is the system of record for accounts, people,
+  opportunities, relationships, lists, views, tasks, cadence, and every local
+  field. No provider, no sync job, no token. Portable across SQLite, Postgres,
+  and D1.
+- **Connected (HubSpot / Salesforce)** — the source CRM stays authoritative for
+  its own fields. CRM is a scoped companion for record work, lists, views,
+  tasks, evidence, and analysis. HubSpot maps companies/contacts/deals;
+  Salesforce maps Account/Contact/Opportunity.
+
+Either way, local attributes, lists, and entry values are yours. The `hybrid`
+mode is deprecated: per-attribute authority expresses everything it promised.
+
+### Provider writes are a handoff, and say so
+
+CRM prepares a provider change as a reviewable proposal, shows the exact
+before/after diff, and opens the record in HubSpot or Salesforce to finish it.
+It does not complete upstream writes and never reports one as applied. That is
+the intended flow, not an error — a proposal awaiting completion is presented as
+the next step, not as a failure.
+
+## Guardrails
+
+Provider credentials live only in workspace Connections; CRM never accepts,
+stores, or returns a token. The mirror holds configured cohorts and allow-listed
+fields — unknown fields are remote-only, sensitive fields default to redacted.
+Raw provider payloads, transcripts, media, and base64 bodies never enter SQL;
+evidence is a URL or id plus a bounded quote. Ownership, amount, stage,
+deletion, bulk scope, and external side effects always require an exact preview
+and approval. Email and domain are matching signals, never identity keys.
+
+Full detail: [`AGENTS.md`](AGENTS.md) for the operating rules, the
+[`crm` skill](.agents/skills/crm/SKILL.md) for workflows, and
+[the CRM contract](docs/architecture/crm-contract.md) for identity, field
+policy, access scope, and the write-policy matrix.
+
+## Set up
+
+1. Open **Set up CRM** and choose **Start with Native SQL** to use CRM with no
+   external service.
+2. To connect a provider, authorize HubSpot or Salesforce in shared **Settings →
+   Connections** and grant it to CRM. OAuth and refresh tokens stay in workspace
+   Connections. Salesforce production is the default; for a sandbox use
+   **Authorize the sandbox directly** on Set up CRM, and the chosen login
+   environment is retained for token refresh.
+3. Pick the granted connection and a recent history window. HubSpot may be
+   narrowed to deal pipeline IDs; Salesforce starts with recently updated
+   Accounts, Contacts, and Opportunities.
+4. CRM mirrors that cohort and its allow-listed fields only. Confirm the
+   connection actor's access before relying on a mirrored record.
+
+## Local development
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Set `DATABASE_URL` for persistent deployment storage. Native SQL needs no
+external credentials. Connect providers from the workspace Connections surface;
+never put provider secrets in `.env`.
+
+For live testing, use an already-authorized shared Connection, choose a small
+recent cohort, verify the resulting records and access scope, then exercise a
+proposal without completing the provider change. Record only connection labels,
+counts, and non-sensitive results.

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,98 @@
+import type { ActionRunContext } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+/**
+ * A boolean flag that survives a query string. `z.boolean()` rejects "true" and
+ * `z.coerce.boolean()` reads "false" as true, so neither can carry a flag on a
+ * `http: { method: "GET" }` action.
+ */
+export const queryFlag = z
+  .union([z.boolean(), z.enum(["true", "false", "1", "0"])])
+  .transform((value) => value === true || value === "true" || value === "1")
+  .default(false);
+
+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-attribute-utils.ts

@@ -0,0 +1,219 @@
+/**
+ * Shared plumbing for the CRM attribute (typed schema) actions.
+ *
+ * `crm_field_policies` IS the attribute table — there is no parallel one — so
+ * every helper here reads and writes that table and translates it to the
+ * `CrmAttributeDefinition` shape the contract publishes.
+ */
+
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, asc, eq, inArray } from "drizzle-orm";
+
+import { getDb, schema } from "../server/db/index.js";
+import { CrmAttributeValueError } from "../server/lib/record-fields.js";
+import {
+  ATTRIBUTE_TYPE_SPECS,
+  type CrmAttributeType,
+} from "../shared/crm-attributes.js";
+import type {
+  CrmAttributeDefinition,
+  CrmAttributeOption,
+} from "../shared/crm-contract.js";
+
+export type CrmAttributeRow = typeof schema.crmFieldPolicies.$inferSelect;
+export type CrmAttributeOptionRow =
+  typeof schema.crmAttributeOptions.$inferSelect;
+
+/** Longest attribute slug we will mint; the column is untyped TEXT. */
+const MAX_API_SLUG_LENGTH = 64;
+
+// The single `attributeType -> value_type` mapping lives in
+// `shared/crm-attributes.ts` so server-side writers (native adapter, mirror)
+// can use it too without an actions/ -> server/ import.
+export { legacyValueTypeFor } from "../shared/crm-attributes.js";
+
+/**
+ * Immutable snake_case slug for a title. Minted once at create time: the slug
+ * is the `field_name` every stored value row is keyed by, so renaming it would
+ * orphan history rather than rename anything.
+ */
+export function toApiSlug(title: string): string {
+  const slug = title
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, MAX_API_SLUG_LENGTH)
+    .replace(/_+$/g, "");
+  if (!slug) {
+    throw new CrmAttributeValueError(
+      "crm-attribute-slug",
+      `Cannot derive an attribute slug from the title "${title}". Use a title containing letters or digits.`,
+    );
+  }
+  return slug;
+}
+
+export function requireAttributeType(type: CrmAttributeType): void {
+  if (ATTRIBUTE_TYPE_SPECS[type].systemOnly) {
+    throw new CrmAttributeValueError(
+      "crm-attribute-system-type",
+      `Attribute type "${type}" is created by the system only and cannot be authored. Use a different type.`,
+    );
+  }
+}
+
+/**
+ * Stored JSON config, or a typed error. An unreadable blob is NOT silently
+ * reported as an empty config — an attribute whose currency code cannot be read
+ * must fail loudly, not render as "no currency configured".
+ */
+export function parseAttributeJson(
+  attributeId: string,
+  column: "config_json" | "fill_config_json",
+  raw: string,
+): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CrmAttributeValueError(
+      "crm-attribute-config-unreadable",
+      `Attribute ${attributeId} has an unreadable ${column}. Repair it before reading or editing this attribute.`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CrmAttributeValueError(
+      "crm-attribute-config-unreadable",
+      `Attribute ${attributeId} has a non-object ${column}. Repair it before reading or editing this attribute.`,
+    );
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export function toAttributeOption(
+  row: CrmAttributeOptionRow,
+): CrmAttributeOption {
+  return {
+    id: row.id,
+    value: row.value,
+    title: row.title,
+    ...(row.color === null ? {} : { color: row.color }),
+    position: row.position,
+    archived: row.archived,
+    targetDays: row.targetDays,
+    celebrate: row.celebrate,
+  };
+}
+
+export function toAttributeDefinition(
+  row: CrmAttributeRow,
+  options: CrmAttributeOption[] = [],
+): CrmAttributeDefinition {
+  return {
+    id: row.id,
+    connectionId: row.connectionId,
+    target: row.target,
+    // `object_type` is populated for every attribute, including list ones where
+    // it mirrors `target_id`; `target_id` is null on rows written by adapters
+    // that predate the typed surface.
+    targetId: row.targetId ?? row.objectType,
+    // Same relationship in reverse: `field_name` is the NOT NULL column the
+    // value writer keys on, and the migration seeded `api_slug` from it.
+    apiSlug: row.apiSlug ?? row.fieldName,
+    label: row.label,
+    ...(row.description === null ? {} : { description: row.description }),
+    attributeType: row.attributeType,
+    multi: row.multi,
+    authority: row.authority,
+    historyTracked: row.historyTracked,
+    uniqueValue: row.uniqueValue,
+    archived: row.archived,
+    position: row.position,
+    inverseAttributeId: row.inverseAttributeId,
+    fillMode: row.fillMode,
+    fillConfig: parseAttributeJson(
+      row.id,
+      "fill_config_json",
+      row.fillConfigJson,
+    ),
+    config: parseAttributeJson(row.id, "config_json", row.configJson),
+    options,
+    storagePolicy: row.storagePolicy,
+    sensitive: row.sensitive,
+    readable: row.readable,
+    createable: row.createable,
+    updateable: row.updateable,
+    required: row.required,
+  };
+}
+
+/** Access-scoped options for a set of attributes, keyed by attribute id. */
+export async function loadAttributeOptions(input: {
+  attributeIds: string[];
+  includeArchived: boolean;
+}): Promise<Map<string, CrmAttributeOption[]>> {
+  const byAttribute = new Map<string, CrmAttributeOption[]>();
+  if (input.attributeIds.length === 0) return byAttribute;
+  const rows = await getDb()
+    .select()
+    .from(schema.crmAttributeOptions)
+    .where(
+      and(
+        inArray(schema.crmAttributeOptions.attributeId, input.attributeIds),
+        ...(input.includeArchived
+          ? []
+          : [eq(schema.crmAttributeOptions.archived, false)]),
+        accessFilter(
+          schema.crmAttributeOptions,
+          schema.crmAttributeOptionShares,
+        ),
+      ),
+    )
+    .orderBy(
+      asc(schema.crmAttributeOptions.position),
+      asc(schema.crmAttributeOptions.value),
+    );
+  for (const row of rows) {
+    const list = byAttribute.get(row.attributeId) ?? [];
+    list.push(toAttributeOption(row));
+    byAttribute.set(row.attributeId, list);
+  }
+  return byAttribute;
+}
+
+/**
+ * Load one attribute the caller may edit. `assertAccess` is the authority on
+ * the decision; the row is re-read through `accessFilter` so a caller can never
+ * observe a row the list surface would hide.
+ */
+export async function requireEditableAttribute(
+  attributeId: string,
+): Promise<CrmAttributeRow> {
+  await assertAccess("crm-field-policy", attributeId, "editor");
+  const [row] = await getDb()
+    .select()
+    .from(schema.crmFieldPolicies)
+    .where(
+      and(
+        eq(schema.crmFieldPolicies.id, attributeId),
+        accessFilter(
+          schema.crmFieldPolicies,
+          schema.crmFieldPolicyShares,
+          undefined,
+          "editor",
+        ),
+      ),
+    )
+    .limit(1);
+  if (!row) {
+    throw new CrmAttributeValueError(
+      "crm-attribute-not-found",
+      `CRM attribute ${attributeId} was not found.`,
+    );
+  }
+  return row;
+}
+
+export { CrmAttributeValueError };

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-data-program-actions.ts

@@ -0,0 +1,15 @@
+import { initDataPrograms } from "@agent-native/core/data-programs";
+
+import { CRM_APP_ID } from "../server/lib/provider-api.js";
+import getCrmPipelineData from "./get-crm-pipeline-data.js";
+
+export function getCrmDataProgramActions() {
+  return { "get-crm-pipeline-data": getCrmPipelineData };
+}
+
+export function initCrmDataPrograms(): void {
+  initDataPrograms({
+    appId: CRM_APP_ID,
+    getActions: getCrmDataProgramActions,
+  });
+}