@agent-native/core 0.123.0 → 0.123.2

package/corpus/templates/crm/shared/crm-contract.ts

@@ -0,0 +1,417 @@
+import type { CrmAttributeType } from "./crm-attributes.js";
+
+export {
+  ATTRIBUTE_TYPE_SPECS,
+  CRM_ATTRIBUTE_TYPES,
+  type CrmAttributeType,
+} from "./crm-attributes.js";
+
+export const CRM_PROVIDERS = [
+  "hubspot",
+  "salesforce",
+  "native",
+  "custom",
+] as const;
+
+export type CrmProvider = (typeof CRM_PROVIDERS)[number];
+
+/**
+ * `hybrid` is DEPRECATED. Per-field `authority` on an attribute expresses
+ * everything hybrid promised, per field instead of per connection. The enum
+ * value stays so existing rows remain valid — treat it as `mirrored`
+ * everywhere and do not offer it in new UI or docs.
+ */
+export const CRM_CONNECTION_MODES = ["connected", "hybrid", "native"] as const;
+
+export type CrmConnectionMode = (typeof CRM_CONNECTION_MODES)[number];
+
+export const CRM_OBJECT_KINDS = [
+  "account",
+  "person",
+  "opportunity",
+  "activity",
+  "task",
+  "custom",
+] as const;
+
+export type CrmObjectKind = (typeof CRM_OBJECT_KINDS)[number];
+
+export const CRM_FIELD_STORAGE_POLICIES = [
+  "mirrored",
+  "remote-only",
+  "redacted",
+  "derived-local",
+  "local-authoritative",
+] as const;
+
+export type CrmFieldStoragePolicy = (typeof CRM_FIELD_STORAGE_POLICIES)[number];
+
+export type CrmScalar = string | number | boolean | null;
+export type CrmValue = CrmScalar | CrmScalar[] | { [key: string]: CrmValue };
+
+export interface CrmConnectionRef {
+  connectionId: string;
+  provider: CrmProvider;
+  accountId?: string;
+  actorId?: string;
+}
+
+export interface CrmObjectRef extends CrmConnectionRef {
+  objectType: string;
+  kind: CrmObjectKind;
+}
+
+export interface CrmRecordRef extends CrmObjectRef {
+  remoteId: string;
+  localId?: string;
+}
+
+export interface CrmAccessScope {
+  key: string;
+  actorId?: string;
+  grantId?: string;
+  mode: "user" | "service-account" | "native";
+  objectReadable: boolean;
+  objectCreateable: boolean;
+  objectUpdateable: boolean;
+  objectDeleteable: boolean;
+  recordVisibility: "actor" | "cohort" | "workspace" | "unknown";
+  fieldPermissionsHash?: string;
+  sharingFingerprint?: string;
+}
+
+export interface CrmFieldDefinition {
+  name: string;
+  label: string;
+  valueType:
+    | "string"
+    | "number"
+    | "boolean"
+    | "date"
+    | "datetime"
+    | "currency"
+    | "percent"
+    | "enum"
+    | "multi-enum"
+    | "reference"
+    | "json";
+  storagePolicy: CrmFieldStoragePolicy;
+  sensitive: boolean;
+  readable: boolean;
+  createable: boolean;
+  updateable: boolean;
+  required: boolean;
+  options?: Array<{ value: string; label: string; active?: boolean }>;
+  referencedObjectType?: string;
+  /**
+   * The typed-attribute surface a field-policy writer should stamp onto
+   * `crm_field_policies`. Optional: providers that only discover the legacy
+   * `valueType` (HubSpot, Salesforce) leave this unset and the writer falls
+   * back to `text`, matching the column's own default.
+   */
+  attributeType?: CrmAttributeType;
+  multi?: boolean;
+  /** `{ currency: { code } }`, `{ reference: { allowedObjectTypes } }`, … */
+  config?: Record<string, unknown>;
+}
+
+export const CRM_ATTRIBUTE_AUTHORITIES = [
+  "provider",
+  "derived-local",
+  "local-authoritative",
+] as const;
+
+export type CrmAttributeAuthority = (typeof CRM_ATTRIBUTE_AUTHORITIES)[number];
+
+export const CRM_ATTRIBUTE_FILL_MODES = [
+  "agent-summarize",
+  "agent-classify",
+  "agent-research",
+  "formula",
+] as const;
+
+export type CrmAttributeFillMode = (typeof CRM_ATTRIBUTE_FILL_MODES)[number];
+
+export const CRM_ACTOR_TYPES = [
+  "user",
+  "agent",
+  "automation",
+  "provider",
+  "system",
+] as const;
+
+export type CrmActorType = (typeof CRM_ACTOR_TYPES)[number];
+
+export interface CrmAttributeOption {
+  id: string;
+  value: string;
+  title: string;
+  color?: string;
+  position: number;
+  archived: boolean;
+  /** `status` only — stage SLA in days. */
+  targetDays?: number | null;
+  /** `status` only. */
+  celebrate?: boolean;
+}
+
+/**
+ * A typed attribute. Persisted in `crm_field_policies`, which is the attribute
+ * table — there is no parallel attributes table.
+ */
+export interface CrmAttributeDefinition {
+  id: string;
+  connectionId: string;
+  target: "object" | "list";
+  /** objectType for `object`, listId for `list`. */
+  targetId: string;
+  apiSlug: string;
+  label: string;
+  description?: string;
+  attributeType: CrmAttributeType;
+  multi: boolean;
+  authority: CrmAttributeAuthority;
+  historyTracked: boolean;
+  uniqueValue: boolean;
+  archived: boolean;
+  position: number;
+  inverseAttributeId?: string | null;
+  fillMode?: CrmAttributeFillMode | null;
+  /** Agent/formula fill configuration. Never auto-runs; manual trigger only. */
+  fillConfig?: Record<string, unknown>;
+  /** `{ currency: { code } }`, `{ reference: { allowedObjectTypes } }`, … */
+  config?: Record<string, unknown>;
+  options?: CrmAttributeOption[];
+  storagePolicy: CrmFieldStoragePolicy;
+  sensitive: boolean;
+  readable: boolean;
+  createable: boolean;
+  updateable: boolean;
+  required: boolean;
+}
+
+/**
+ * Lists are always local-authoritative, on every backend including HubSpot and
+ * Salesforce. An imported list keeps its provider origin for reference only.
+ */
+export interface CrmListDefinition {
+  id: string;
+  connectionId: string;
+  name: string;
+  apiSlug: string;
+  parentObjectType: string;
+  description?: string;
+  defaultViewId?: string | null;
+  archived: boolean;
+  position: number;
+  source: "local" | "imported";
+  sourceRemoteId?: string | null;
+  lastSyncedAt?: string | null;
+}
+
+/**
+ * One record's membership in one list. A record may appear in the same list
+ * more than once — there is deliberately no unique `(listId, recordId)`.
+ */
+export interface CrmListEntry {
+  id: string;
+  listId: string;
+  recordId: string;
+  position: number;
+  createdByActorType: CrmActorType;
+  createdByActorId?: string | null;
+  createdAt: string;
+}
+
+export interface CrmSavedViewDefinition {
+  id: string;
+  name: string;
+  description?: string;
+  viewKind: "table" | "board";
+  targetKind: "object" | "list";
+  /** objectType for `object`, listId for `list`. */
+  targetId?: string | null;
+  /** Board views only; must reference a `status` attribute. */
+  groupByAttributeId?: string | null;
+  columns: string[];
+  /**
+   * Filter condition values may be the literal `"@currentUser"`, resolved
+   * server-side against the calling actor — never resolved on the client.
+   */
+  filters: Record<string, unknown>;
+  sort: Array<{ field: string; direction: "asc" | "desc" }>;
+  /**
+   * Projection of the framework `visibility` column on `crm_saved_views`:
+   * `private` reads as personal, `org` as shared. There is no separate column.
+   */
+  audience: "personal" | "shared";
+  pinned: boolean;
+}
+
+export const CRM_CURRENT_USER_TOKEN = "@currentUser";
+
+export interface CrmObjectDefinition extends CrmObjectRef {
+  label: string;
+  pluralLabel: string;
+  custom: boolean;
+  queryable: boolean;
+  searchable: boolean;
+  createable: boolean;
+  updateable: boolean;
+  deleteable: boolean;
+  fields: CrmFieldDefinition[];
+}
+
+export interface CrmRecord {
+  ref: CrmRecordRef;
+  displayName: string;
+  fields: Record<string, CrmValue>;
+  remoteRevision?: string;
+  remoteUpdatedAt?: string;
+  deleted: boolean;
+  accessScope: CrmAccessScope;
+  provenance: CrmProvenance[];
+}
+
+export interface CrmRelationship {
+  from: CrmRecordRef;
+  to: CrmRecordRef;
+  relationshipType: string;
+  label?: string;
+  inverseLabel?: string;
+  sourceField?: string;
+}
+
+export interface CrmProvenance {
+  provider: CrmProvider;
+  connectionId: string;
+  objectType: string;
+  remoteId: string;
+  fieldName?: string;
+  remoteRevision?: string;
+  observedAt: string;
+  evidenceRef?: string;
+}
+
+export interface CrmSyncScope {
+  objectType: string;
+  pipelineIds?: string[];
+  ownerIds?: string[];
+  recordIds?: string[];
+  associatedRecordIds?: string[];
+  updatedAfter?: string;
+  includeDeleted?: boolean;
+}
+
+export interface CrmSyncPage {
+  records: CrmRecord[];
+  relationships: CrmRelationship[];
+  nextCursor?: string;
+  complete: boolean;
+}
+
+export interface CrmMutation {
+  operation: "create" | "update" | "delete" | "associate" | "disassociate";
+  record: CrmRecordRef;
+  fields?: Record<string, CrmValue>;
+  relationship?: CrmRelationship;
+  expectedRemoteRevision?: string;
+  idempotencyKey: string;
+}
+
+export interface CrmMutationResult {
+  status: "applied" | "conflict" | "rejected";
+  record?: CrmRecord;
+  remoteRevision?: string;
+  message?: string;
+}
+
+export interface CrmAdapterCapabilities {
+  schemaDiscovery: boolean;
+  customObjects: boolean;
+  search: boolean;
+  incrementalSync: boolean;
+  deletedRecordSync: boolean;
+  conditionalMutations: boolean;
+  labeledRelationships: boolean;
+  perFieldPermissions: boolean;
+  perRecordPermissions: boolean;
+}
+
+export interface CrmAdapter {
+  readonly connection: CrmConnectionRef;
+  readonly capabilities: CrmAdapterCapabilities;
+  discoverObjects(): Promise<CrmObjectDefinition[]>;
+  describeObject(objectType: string): Promise<CrmObjectDefinition>;
+  syncPage(input: {
+    scope: CrmSyncScope;
+    fieldAllowList: string[];
+    cursor?: string;
+    limit: number;
+  }): Promise<CrmSyncPage>;
+  getRecord(input: {
+    record: CrmRecordRef;
+    fields: string[];
+  }): Promise<CrmRecord | null>;
+  search(input: {
+    objectTypes: string[];
+    query: string;
+    fields: string[];
+    limit: number;
+    cursor?: string;
+  }): Promise<CrmSyncPage>;
+  listRelationships(input: {
+    record: CrmRecordRef;
+    targetObjectTypes?: string[];
+    limit: number;
+    cursor?: string;
+  }): Promise<{
+    relationships: CrmRelationship[];
+    nextCursor?: string;
+    complete: boolean;
+  }>;
+  applyMutation(mutation: CrmMutation): Promise<CrmMutationResult>;
+}
+
+export const CRM_WRITE_DECISIONS = [
+  "execute",
+  "propose",
+  "require-approval",
+  "deny",
+] as const;
+
+export type CrmWriteDecision = (typeof CRM_WRITE_DECISIONS)[number];
+
+export interface CrmWritePolicyInput {
+  initiatedBy: "human" | "agent" | "automation";
+  target: "local" | "provider";
+  reversibility: "reversible" | "compensatable" | "destructive";
+  scope: "single-field" | "single-record" | "bulk";
+  risk: "routine" | "ownership" | "amount" | "stage" | "external-side-effect";
+  delegatedAuthority: boolean;
+  storedAutomationPolicy: boolean;
+}
+
+export function decideCrmWritePolicy(
+  input: CrmWritePolicyInput,
+): CrmWriteDecision {
+  if (
+    input.reversibility === "destructive" ||
+    input.scope === "bulk" ||
+    input.risk !== "routine"
+  ) {
+    return input.initiatedBy === "human" ? "execute" : "require-approval";
+  }
+
+  if (input.initiatedBy === "human") return "execute";
+
+  if (input.initiatedBy === "automation") {
+    if (input.target === "provider") return "propose";
+    return input.storedAutomationPolicy && input.delegatedAuthority
+      ? "execute"
+      : "deny";
+  }
+
+  if (input.target === "local") return "execute";
+  return "propose";
+}

package/corpus/templates/crm/shared/crm-navigation.ts

@@ -0,0 +1,190 @@
+/**
+ * The CRM navigation vocabulary: which surfaces exist, the path each one lives
+ * at, and how to read the current selection back out of a path.
+ *
+ * The agent (`navigate`, `view-screen`) and the browser route hook have to mean
+ * the same thing by "the board for this list", so the view union, the path
+ * builder, and the selection parser live here rather than once per surface.
+ * Two copies of this map is how the agent ends up navigating somewhere the UI
+ * does not report back.
+ */
+
+export const CRM_SETTINGS_SECTIONS = [
+  "connection",
+  "fields",
+  "lists",
+  "intelligence",
+  "advanced",
+] as const;
+
+export type CrmSettingsSection = (typeof CRM_SETTINGS_SECTIONS)[number];
+
+export const CRM_RECORD_KINDS = ["account", "person", "opportunity"] as const;
+
+export type CrmRecordKind = (typeof CRM_RECORD_KINDS)[number];
+
+export const CRM_VIEWS = [
+  "work",
+  "account",
+  "person",
+  "opportunity",
+  "records",
+  "record",
+  "lists",
+  "views",
+  "board",
+  "tasks",
+  "proposals",
+  "dashboard",
+  "ask",
+  "setup",
+  "settings",
+] as const;
+
+export type CrmView = (typeof CRM_VIEWS)[number];
+
+/**
+ * `board` shares the `/views` route: a board is a presentation mode of one
+ * saved view or list, not a route of its own. `viewFromPath` therefore never
+ * returns it — only `navigate` accepts it as a destination.
+ */
+export const CRM_VIEW_PATHS: Record<Exclude<CrmView, "record">, string> = {
+  work: "/",
+  account: "/accounts",
+  person: "/people",
+  opportunity: "/opportunities",
+  records: "/records",
+  lists: "/lists",
+  views: "/views",
+  board: "/views",
+  tasks: "/tasks",
+  proposals: "/proposals",
+  dashboard: "/dashboard",
+  ask: "/ask",
+  setup: "/setup",
+  settings: "/settings",
+};
+
+export interface CrmNavigationTarget {
+  view?: string;
+  recordId?: string;
+  listId?: string;
+  viewId?: string;
+  dashboardId?: string;
+  kind?: CrmRecordKind;
+  query?: string;
+  settingsSection?: CrmSettingsSection;
+}
+
+export function viewFromPath(pathname: string): CrmView {
+  if (pathname.startsWith("/records/")) return "record";
+  if (pathname.startsWith("/records")) return "records";
+  if (pathname.startsWith("/accounts")) return "account";
+  if (pathname.startsWith("/people")) return "person";
+  if (pathname.startsWith("/opportunities")) return "opportunity";
+  if (pathname.startsWith("/lists")) return "lists";
+  if (pathname.startsWith("/tasks")) return "tasks";
+  if (pathname.startsWith("/proposals")) return "proposals";
+  if (pathname.startsWith("/views")) return "views";
+  if (pathname.startsWith("/dashboard")) return "dashboard";
+  if (pathname.startsWith("/ask")) return "ask";
+  if (pathname.startsWith("/setup")) return "setup";
+  if (pathname.startsWith("/settings")) return "settings";
+  return "work";
+}
+
+/**
+ * The complete path — including search — for a navigation target.
+ *
+ * A destination the UI cannot actually open is thrown, not silently degraded to
+ * an index page: "navigated to the board" while the board never opened is the
+ * failure mode the root CLAUDE.md forbids.
+ */
+export function crmNavigationPath(target: CrmNavigationTarget): string {
+  if (target.view === "record") {
+    if (!target.recordId) {
+      throw new Error("recordId is required when navigating to a CRM record.");
+    }
+    return `/records/${encodeURIComponent(target.recordId)}`;
+  }
+  if (target.view === "settings" && target.settingsSection) {
+    return `/settings/${target.settingsSection}`;
+  }
+  if (target.view === "board" && !target.viewId && !target.listId) {
+    throw new Error(
+      "listId or viewId is required when navigating to a CRM board; /views on its own is the saved-view index.",
+    );
+  }
+
+  const params = new URLSearchParams();
+  let base = CRM_VIEW_PATHS[target.view as Exclude<CrmView, "record">] ?? "/";
+  // A saved view or a list always opens on the /views surface; /lists is only
+  // the index of lists.
+  if (
+    (target.view === "views" ||
+      target.view === "board" ||
+      target.view === "lists") &&
+    (target.viewId || target.listId)
+  ) {
+    base = "/views";
+    if (target.viewId) params.set("view", target.viewId);
+    else params.set("list", target.listId!);
+  }
+  if (target.view === "board") params.set("mode", "board");
+  if (target.view === "records" && target.kind) params.set("kind", target.kind);
+  if (target.view === "dashboard" && target.dashboardId) {
+    params.set("id", target.dashboardId);
+  }
+  if (target.query) params.set("q", target.query);
+  return params.size ? `${base}?${params}` : base;
+}
+
+export interface CrmNavigationSelection {
+  viewId?: string;
+  listId?: string;
+  dashboardId?: string;
+  kind?: CrmRecordKind;
+  mode?: "table" | "board";
+  query?: string;
+  settingsSection?: CrmSettingsSection;
+}
+
+/**
+ * The selection carried by a visited path. `null` means no path was published
+ * — which is not the same as a path with nothing selected, and callers must be
+ * able to tell those apart.
+ */
+export function parseCrmNavigationSelection(
+  pathAndSearch: string | null | undefined,
+): CrmNavigationSelection | null {
+  if (typeof pathAndSearch !== "string" || !pathAndSearch) return null;
+  let url: URL;
+  try {
+    url = new URL(pathAndSearch, "http://crm.invalid");
+  } catch {
+    return null;
+  }
+  const params = url.searchParams;
+  const kind = params.get("kind");
+  const mode = params.get("mode");
+  const section = url.pathname.split("/settings/")[1]?.split("/")[0];
+  return {
+    ...(params.get("view") ? { viewId: params.get("view")! } : {}),
+    ...(params.get("list") ? { listId: params.get("list")! } : {}),
+    ...(params.get("id") ? { dashboardId: params.get("id")! } : {}),
+    ...(isRecordKind(kind) ? { kind } : {}),
+    ...(mode === "table" || mode === "board" ? { mode } : {}),
+    ...(params.get("q") ? { query: params.get("q")! } : {}),
+    ...(isSettingsSection(section) ? { settingsSection: section } : {}),
+  };
+}
+
+function isRecordKind(value: string | null): value is CrmRecordKind {
+  return CRM_RECORD_KINDS.includes(value as CrmRecordKind);
+}
+
+function isSettingsSection(
+  value: string | undefined,
+): value is CrmSettingsSection {
+  return CRM_SETTINGS_SECTIONS.includes(value as CrmSettingsSection);
+}

package/corpus/templates/crm/shared/crm-sales-config.ts

@@ -0,0 +1,63 @@
+import type { ActionRunContext } from "@agent-native/core/action";
+
+import type { CrmWritePolicyInput } from "./crm-contract.js";
+
+export const CRM_SALES_ROUTINE_LOCAL_POLICY_ID =
+  "crm-sales-routine-local-v1" as const;
+
+export interface CrmSalesConfigPack {
+  id: "crm-sales-v1";
+  version: 1;
+  delegatedWritePolicies: readonly [
+    {
+      id: typeof CRM_SALES_ROUTINE_LOCAL_POLICY_ID;
+      target: "local";
+      operation: "update";
+      reversibility: "compensatable";
+      scopes: readonly ["single-field", "single-record"];
+      risk: "routine";
+    },
+  ];
+}
+
+export const CRM_SALES_CONFIG_PACK: CrmSalesConfigPack = {
+  id: "crm-sales-v1",
+  version: 1,
+  delegatedWritePolicies: [
+    {
+      id: CRM_SALES_ROUTINE_LOCAL_POLICY_ID,
+      target: "local",
+      operation: "update",
+      reversibility: "compensatable",
+      scopes: ["single-field", "single-record"],
+      risk: "routine",
+    },
+  ],
+};
+
+export function resolveCrmSalesDelegatedWrite(input: {
+  context?: ActionRunContext;
+  operation: "update";
+  policy: CrmWritePolicyInput;
+}) {
+  const policyId = input.context?.automation?.policyId;
+  const policy = CRM_SALES_CONFIG_PACK.delegatedWritePolicies.find(
+    (candidate) => candidate.id === policyId,
+  );
+  if (input.context?.caller !== "automation" || !policy) {
+    return { delegatedAuthority: false, storedAutomationPolicy: false };
+  }
+
+  const matches =
+    policy.operation === input.operation &&
+    policy.target === input.policy.target &&
+    policy.reversibility === input.policy.reversibility &&
+    (input.policy.scope === "single-field" ||
+      input.policy.scope === "single-record") &&
+    policy.scopes.includes(input.policy.scope) &&
+    policy.risk === input.policy.risk;
+  return {
+    delegatedAuthority: matches,
+    storedAutomationPolicy: matches,
+  };
+}

package/corpus/templates/crm/ssr-entry.ts

@@ -0,0 +1,11 @@
+import { createRequestHandler } from "react-router";
+
+const handler = createRequestHandler(
+  () => import("virtual:react-router/server-build"),
+);
+
+export default {
+  async fetch(request: Request) {
+    return handler(request);
+  },
+};

package/corpus/templates/crm/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "@agent-native/core/tsconfig.base.json",
+  "compilerOptions": {
+    "ignoreDeprecations": "6.0",
+    "rootDirs": [".", "./.react-router/types"],
+    "paths": {
+      "*": ["./*"],
+      "@/*": ["./app/*"],
+      "@shared/*": ["./shared/*"]
+    }
+  },
+  "include": [
+    "app/**/*",
+    "server/**/*",
+    "shared/**/*",
+    "actions/**/*",
+    "vite.config.ts",
+    "vitest.config.ts",
+    "react-router.config.ts",
+    ".react-router/types/**/*",
+    ".generated/**/*"
+  ],
+  "exclude": ["**/*.test.ts", "**/*.spec.ts"]
+}