@agent-native/core 0.123.0 → 0.123.2

package/corpus/templates/crm/actions/view-screen.ts

@@ -0,0 +1,324 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { readAppStateForCurrentTab } from "@agent-native/core/application-state";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, asc, desc, eq } from "drizzle-orm";
+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 {
+  getCrmOverview,
+  getCrmRecord,
+  getCrmRecordReadContext,
+  getReadThroughRelationshipSummaries,
+  listCrmProposals,
+  listCrmSavedViews,
+  listCrmSignals,
+  listCrmTasks,
+} from "../server/db/crm-store.js";
+import { crmDashboardStore, getDb, schema } from "../server/db/index.js";
+import { loadCrmSavedView, queryCrmRecords } from "../server/lib/crm-query.js";
+import {
+  parseCrmNavigationSelection,
+  type CrmNavigationSelection,
+  type CrmView,
+} from "../shared/crm-navigation.js";
+
+export default defineAction({
+  description:
+    "Return an access-scoped snapshot of the visible CRM screen: the current selection plus the relevant records, lists, saved view and its board grouping, tasks, proposals, or setup state.",
+  schema: z.object({}),
+  http: false,
+  readOnly: true,
+  run: async (_args, ctx?: ActionRunContext) => {
+    const navigation = (await readAppStateForCurrentTab("navigation")) as {
+      view?: CrmView;
+      path?: string;
+      recordId?: string;
+      viewId?: string;
+      dashboardId?: string;
+      query?: string;
+      settingsSection?: string;
+    } | null;
+    const url = await readAppStateForCurrentTab("__url__");
+    // The route hook publishes the visited path with its search string, and for
+    // the list/board surfaces the search params ARE the selection. Reading them
+    // back here beats maintaining a second copy of that state.
+    const parsed = parseCrmNavigationSelection(
+      navigation?.path ?? (typeof url === "string" ? url : null),
+    );
+    const selection = resolveSelection(navigation, parsed);
+    const actorEmail = ctx?.userEmail ?? getRequestUserEmail() ?? null;
+    const screen: Record<string, unknown> = { navigation, url, selection };
+
+    switch (navigation?.view) {
+      case "record":
+        if (selection.recordId) {
+          [screen.record, screen.signals] = await Promise.all([
+            readVisibleRecord(selection.recordId, ctx),
+            listCrmSignals({ recordId: selection.recordId, limit: 50 }),
+          ]);
+        } else {
+          screen.record = null;
+          screen.signals = [];
+        }
+        break;
+      case "account":
+      case "person":
+      case "opportunity":
+      case "records":
+        screen.records = await queryCrmRecords(
+          {
+            // /records defaults to the accounts tab when the URL names no kind.
+            kind:
+              navigation.view === "records"
+                ? (selection.kind ?? "account")
+                : navigation.view,
+            ...(selection.query ? { query: selection.query } : {}),
+            ...(selection.viewId ? { viewId: selection.viewId } : {}),
+            limit: 50,
+          },
+          { actorEmail },
+        );
+        break;
+      case "lists":
+        screen.lists = await visibleLists();
+        break;
+      case "views":
+      case "board":
+        screen.savedViews = await listCrmSavedViews({ limit: 50 });
+        if (selection.viewId) {
+          const view = await loadCrmSavedView(selection.viewId);
+          screen.activeView = view;
+          screen.records = await queryCrmRecords(
+            { viewId: view.id, limit: 50 },
+            { actorEmail },
+          );
+        } else if (selection.listId) {
+          // null distinguishes "a list is selected but not visible to you"
+          // from "no list is selected", which `selection.listId` still shows.
+          screen.activeList = await visibleList(selection.listId);
+        }
+        break;
+      case "tasks":
+        screen.tasks = await listCrmTasks({ limit: 50 });
+        break;
+      case "proposals":
+        screen.proposals = await listCrmProposals({ limit: 50 });
+        break;
+      case "dashboard":
+        {
+          const dashboards = await crmDashboardStore.list({
+            userEmail: ctx?.userEmail,
+            orgId: ctx?.orgId ?? undefined,
+          });
+          screen.dashboards = dashboards;
+          screen.dashboard = selection.dashboardId
+            ? (dashboards.find(
+                (dashboard: { id: string }) =>
+                  dashboard.id === selection.dashboardId,
+              ) ?? null)
+            : (dashboards[0] ?? null);
+        }
+        break;
+      case "ask":
+        [screen.overview, screen.savedViews] = await Promise.all([
+          getCrmOverview(),
+          listCrmSavedViews({ limit: 20 }),
+        ]);
+        break;
+      case "setup":
+        screen.connections = await visibleConnections();
+        break;
+      case "settings":
+        screen.connections = await visibleConnections();
+        screen.signalTrackers = await visibleSignalTrackers();
+        break;
+      case "work":
+      case undefined:
+        screen.overview = await getCrmOverview();
+        break;
+    }
+
+    return screen;
+  },
+});
+
+interface ResolvedSelection extends CrmNavigationSelection {
+  recordId?: string;
+  /** False when the UI published no path, so an absent field is unknown. */
+  pathReadable: boolean;
+}
+
+/**
+ * The fields the route hook publishes explicitly win; the rest come from the
+ * visited path. `pathReadable` keeps "nothing selected" distinguishable from
+ * "the UI never told us what is selected".
+ */
+function resolveSelection(
+  navigation: {
+    recordId?: string;
+    viewId?: string;
+    dashboardId?: string;
+    query?: string;
+    settingsSection?: string;
+  } | null,
+  parsed: CrmNavigationSelection | null,
+): ResolvedSelection {
+  const viewId = navigation?.viewId ?? parsed?.viewId;
+  const dashboardId = navigation?.dashboardId ?? parsed?.dashboardId;
+  const query = navigation?.query ?? parsed?.query;
+  const settingsSection =
+    (navigation?.settingsSection as CrmNavigationSelection["settingsSection"]) ??
+    parsed?.settingsSection;
+  return {
+    pathReadable: parsed !== null,
+    ...(navigation?.recordId ? { recordId: navigation.recordId } : {}),
+    ...(viewId ? { viewId } : {}),
+    ...(parsed?.listId ? { listId: parsed.listId } : {}),
+    ...(dashboardId ? { dashboardId } : {}),
+    ...(parsed?.kind ? { kind: parsed.kind } : {}),
+    ...(parsed?.mode ? { mode: parsed.mode } : {}),
+    ...(query ? { query } : {}),
+    ...(settingsSection ? { settingsSection } : {}),
+  };
+}
+
+const LIST_COLUMNS = {
+  id: schema.crmLists.id,
+  connectionId: schema.crmLists.connectionId,
+  name: schema.crmLists.name,
+  apiSlug: schema.crmLists.apiSlug,
+  description: schema.crmLists.description,
+  parentObjectType: schema.crmLists.parentObjectType,
+  defaultViewId: schema.crmLists.defaultViewId,
+  archived: schema.crmLists.archived,
+  position: schema.crmLists.position,
+};
+
+async function visibleLists() {
+  return getDb()
+    .select(LIST_COLUMNS)
+    .from(schema.crmLists)
+    .where(
+      and(
+        eq(schema.crmLists.archived, false),
+        accessFilter(schema.crmLists, schema.crmListShares),
+      ),
+    )
+    .orderBy(asc(schema.crmLists.position), asc(schema.crmLists.createdAt))
+    .limit(50);
+}
+
+async function visibleList(listId: string) {
+  const [list] = await getDb()
+    .select(LIST_COLUMNS)
+    .from(schema.crmLists)
+    .where(
+      and(
+        eq(schema.crmLists.id, listId),
+        accessFilter(schema.crmLists, schema.crmListShares),
+      ),
+    )
+    .limit(1);
+  return list ?? null;
+}
+
+async function readVisibleRecord(recordId: string, ctx?: ActionRunContext) {
+  const context = await getCrmRecordReadContext(recordId);
+  if (!context) return null;
+  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) return null;
+  let readThrough;
+  try {
+    readThrough = await loadVerifiedReadThroughRecord({ adapter, context });
+  } catch {
+    return null;
+  }
+  const relatedRecords = await getReadThroughRelationshipSummaries({
+    context,
+    relationships: readThrough.relationships,
+    currentScopes: readThrough.currentScopes,
+  });
+  return getCrmRecord(recordId, {
+    displayName: readThrough.remote.displayName,
+    fields: readThrough.remote.fields,
+    remoteRevision: readThrough.remote.remoteRevision,
+    remoteUpdatedAt: readThrough.remote.remoteUpdatedAt,
+    relatedRecords,
+    accessScope: readThrough.currentScope,
+  });
+}
+
+async function visibleConnections() {
+  return getDb()
+    .select({
+      id: schema.crmConnections.id,
+      provider: schema.crmConnections.provider,
+      label: schema.crmConnections.label,
+      mode: schema.crmConnections.mode,
+      status: schema.crmConnections.status,
+      lastSyncedAt: schema.crmConnections.lastSyncedAt,
+      updatedAt: schema.crmConnections.updatedAt,
+    })
+    .from(schema.crmConnections)
+    .where(accessFilter(schema.crmConnections, schema.crmConnectionShares))
+    .orderBy(desc(schema.crmConnections.updatedAt))
+    .limit(20);
+}
+
+async function visibleSignalTrackers() {
+  const trackers = await getDb()
+    .select({
+      id: schema.crmSignalTrackers.id,
+      name: schema.crmSignalTrackers.name,
+      description: schema.crmSignalTrackers.description,
+      kind: schema.crmSignalTrackers.kind,
+      keywordsJson: schema.crmSignalTrackers.keywordsJson,
+      classifierPrompt: schema.crmSignalTrackers.classifierPrompt,
+      enabled: schema.crmSignalTrackers.enabled,
+      isDefault: schema.crmSignalTrackers.isDefault,
+    })
+    .from(schema.crmSignalTrackers)
+    .where(
+      accessFilter(schema.crmSignalTrackers, schema.crmSignalTrackerShares),
+    )
+    .orderBy(asc(schema.crmSignalTrackers.name));
+  return trackers.map((tracker) => ({
+    ...tracker,
+    keywords: safeKeywords(tracker.keywordsJson),
+    keywordsJson: undefined,
+  }));
+}
+
+function safeKeywords(value: string): string[] {
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return Array.isArray(parsed)
+      ? parsed.filter(
+          (keyword): keyword is string => typeof keyword === "string",
+        )
+      : [];
+  } catch {
+    return [];
+  }
+}

package/corpus/templates/crm/agent-native.app-skill.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": 1,
+  "id": "crm",
+  "displayName": "CRM",
+  "description": "A typed, bitemporal CRM grid with lists, pipelines, and saved board views — running on its own SQL or as a field-policy-aware HubSpot and Salesforce companion.",
+  "mcp": { "serverName": "agent-native-crm" },
+  "local": {
+    "template": "crm",
+    "sourcePath": ".",
+    "defaultUrl": "http://127.0.0.1:8107",
+    "commands": {
+      "install": "pnpm install",
+      "dev": "pnpm dev",
+      "start": "pnpm start"
+    }
+  },
+  "auth": {
+    "mode": "oauth",
+    "setup": "Start with Native SQL without an external connection, or connect HubSpot or Salesforce through workspace Connections. CRM never accepts or stores provider credentials."
+  },
+  "surfaces": [
+    { "id": "crm-workspace", "action": "get-crm-workspace", "path": "/" },
+    { "id": "crm-records", "action": "list-crm-records", "path": "/records" },
+    { "id": "crm-lists", "action": "list-crm-lists", "path": "/lists" },
+    {
+      "id": "crm-saved-views",
+      "action": "list-crm-saved-views",
+      "path": "/views"
+    },
+    { "id": "crm-tasks", "action": "list-crm-tasks", "path": "/tasks" },
+    {
+      "id": "crm-proposals",
+      "action": "list-crm-proposals",
+      "path": "/proposals"
+    },
+    {
+      "id": "crm-pipeline",
+      "action": "get-crm-dashboard",
+      "path": "/dashboard"
+    },
+    {
+      "id": "crm-attributes",
+      "action": "list-crm-attributes",
+      "path": "/settings/fields"
+    },
+    {
+      "id": "crm-signals",
+      "action": "list-crm-signal-hits",
+      "path": "/records"
+    },
+    {
+      "id": "crm-clips-review-recipe",
+      "action": "get-crm-automation-recipe",
+      "path": "/records"
+    }
+  ],
+  "skills": [
+    { "path": ".agents/skills/crm", "visibility": "both", "exportAs": "crm" }
+  ],
+  "hostAdapters": [
+    "codex-plugin",
+    "claude-marketplace",
+    "vercel-skills",
+    "plain-skill",
+    "claude-skill",
+    "chatgpt-mcp",
+    "generic-mcp"
+  ]
+}

package/corpus/templates/crm/app/components/crm/CreateCrmRecordDialog.tsx

@@ -0,0 +1,158 @@
+import { useActionMutation } from "@agent-native/core/client/hooks";
+import { IconPlus } from "@tabler/icons-react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { useNavigate } from "react-router";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import type { CrmKind } from "@/lib/types";
+
+import type { CrmValue } from "../../../shared/crm-contract";
+
+const recordCopy: Record<
+  CrmKind,
+  {
+    noun: string;
+    fieldName: string;
+    fieldLabel: string;
+    fieldPlaceholder: string;
+  }
+> = {
+  account: {
+    noun: "account",
+    fieldName: "domain",
+    fieldLabel: "Website",
+    fieldPlaceholder: "example.com",
+  },
+  person: {
+    noun: "person",
+    fieldName: "email",
+    fieldLabel: "Email",
+    fieldPlaceholder: "name@example.com",
+  },
+  opportunity: {
+    noun: "opportunity",
+    fieldName: "stage",
+    fieldLabel: "Stage",
+    fieldPlaceholder: "Discovery",
+  },
+};
+
+export function CreateCrmRecordDialog({ kind }: { kind: CrmKind }) {
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const copy = recordCopy[kind];
+  const [open, setOpen] = useState(false);
+  const [displayName, setDisplayName] = useState("");
+  const [fieldValue, setFieldValue] = useState("");
+  const create = useActionMutation<
+    { recordId: string },
+    {
+      connectionId?: string;
+      kind: CrmKind;
+      displayName: string;
+      fields?: Record<string, CrmValue>;
+      idempotencyKey?: string;
+    }
+  >("create-crm-record" as never);
+
+  function reset() {
+    setDisplayName("");
+    setFieldValue("");
+  }
+
+  function setDialogOpen(nextOpen: boolean) {
+    setOpen(nextOpen);
+    if (!nextOpen) reset();
+  }
+
+  async function submit() {
+    const fields = fieldValue.trim()
+      ? { [copy.fieldName]: fieldValue.trim() }
+      : undefined;
+    try {
+      const result = await create.mutateAsync({
+        kind,
+        displayName: displayName.trim(),
+        fields,
+      });
+      setDialogOpen(false);
+      void queryClient.invalidateQueries({
+        queryKey: ["action", "list-crm-records"],
+      });
+      toast.success(`Native ${copy.noun} created.`);
+      navigate(`/records/${encodeURIComponent(result.recordId)}`);
+    } catch (error) {
+      toast.error(
+        error instanceof Error
+          ? error.message
+          : `Could not create ${copy.noun}.`,
+      );
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={setDialogOpen}>
+      <DialogTrigger asChild>
+        <Button size="sm" className="gap-2">
+          <IconPlus className="size-4" /> New {copy.noun}
+        </Button>
+      </DialogTrigger>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>Create {copy.noun}</DialogTitle>
+          <DialogDescription>
+            This record lives in the local-authoritative Native SQL CRM. You can
+            connect or mirror another CRM separately.
+          </DialogDescription>
+        </DialogHeader>
+        <div className="grid gap-4 py-2">
+          <div className="grid gap-2">
+            <Label htmlFor={`new-${kind}-name`}>Name</Label>
+            <Input
+              id={`new-${kind}-name`}
+              value={displayName}
+              maxLength={300}
+              autoFocus
+              onChange={(event) => setDisplayName(event.target.value)}
+            />
+          </div>
+          <div className="grid gap-2">
+            <Label htmlFor={`new-${kind}-${copy.fieldName}`}>
+              {copy.fieldLabel}{" "}
+              <span className="text-muted-foreground">(optional)</span>
+            </Label>
+            <Input
+              id={`new-${kind}-${copy.fieldName}`}
+              value={fieldValue}
+              maxLength={500}
+              placeholder={copy.fieldPlaceholder}
+              type={copy.fieldName === "email" ? "email" : "text"}
+              onChange={(event) => setFieldValue(event.target.value)}
+            />
+          </div>
+        </div>
+        <DialogFooter>
+          <Button
+            disabled={!displayName.trim() || create.isPending}
+            onClick={() => void submit()}
+          >
+            {create.isPending ? "Creating…" : `Create ${copy.noun}`}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/corpus/templates/crm/app/components/crm/CrmDashboardPanel.tsx

@@ -0,0 +1,78 @@
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import {
+  GenericChartPanel,
+  MetricCard,
+  type GenericChartConfig,
+} from "@agent-native/toolkit/dashboard";
+
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import type { CrmDashboardPanelConfig } from "@/lib/types";
+
+type PanelResult = {
+  rows: Record<string, unknown>[];
+  schema?: Array<{ name: string; type: string }>;
+  truncated?: boolean;
+};
+
+export function CrmDashboardPanel({
+  dashboardId,
+  panel,
+  dataPanelId = panel.id,
+}: {
+  dashboardId: string;
+  panel: CrmDashboardPanelConfig;
+  dataPanelId?: string;
+}) {
+  const query = useActionQuery<PanelResult>(
+    "get-crm-dashboard-panel" as never,
+    { dashboardId, panelId: dataPanelId } as never,
+  );
+  const error = query.error instanceof Error ? query.error.message : undefined;
+  const rows = query.data?.rows ?? [];
+
+  if (panel.chartType === "metric") {
+    return (
+      <MetricCard
+        title={panel.title}
+        value={metricValue(rows)}
+        description={query.data?.truncated ? "Source is bounded" : undefined}
+        loading={query.isLoading}
+        error={error}
+      />
+    );
+  }
+
+  const chart: GenericChartConfig = {
+    chartType: panel.chartType,
+    xKey: "stage",
+    yKeys: ["pipelineValue", "opportunities"],
+    ...(panel.chartType === "table"
+      ? { columns: ["stage", "pipelineValue", "opportunities"] }
+      : {}),
+  };
+  return (
+    <Card className="border-border/70 bg-card">
+      <CardHeader className="pb-3">
+        <CardTitle className="text-base">{panel.title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <GenericChartPanel
+          data={query.data?.rows}
+          config={panel}
+          chart={chart}
+          loading={query.isLoading}
+          error={error}
+          emptyMessage="No opportunities are available in this pipeline yet."
+        />
+      </CardContent>
+    </Card>
+  );
+}
+
+function metricValue(rows: Record<string, unknown>[]) {
+  return rows.reduce(
+    (total, row) =>
+      total + (typeof row.pipelineValue === "number" ? row.pipelineValue : 0),
+    0,
+  );
+}