@agent-native/core 0.114.16 → 0.115.3

package/corpus/templates/crm/actions/record-crm-smart-signal.ts

@@ -0,0 +1,150 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq } 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 {
+  crmSignalIdempotencyKey,
+  signalTupleError,
+} from "./_crm-signal-utils.js";
+
+export default defineAction({
+  description:
+    "Record one delegated-agent detector hit only after grounding it to an access-scoped evidence excerpt and queued smart run.",
+  schema: z.object({
+    runId: z.string().trim().min(1).max(128),
+    trackerId: z.string().trim().min(1).max(128),
+    recordId: z.string().trim().min(1).max(128),
+    evidenceId: z.string().trim().min(1).max(128),
+    quote: z.string().trim().min(1).max(1_200).refine(isSafeCrmEvidenceExcerpt),
+    confidence: z.coerce.number().finite().min(0).max(100),
+    model: z.string().trim().min(1).max(120),
+    modelVersion: z.string().trim().max(120).optional(),
+    idempotencyKey: z.string().trim().min(1).max(180),
+  }),
+  run: async (args, ctx) => {
+    await Promise.all([
+      assertAccess("crm-record", args.recordId, "editor"),
+      assertAccess("crm-signal-run", args.runId, "editor"),
+      assertAccess("crm-signal-tracker", args.trackerId, "viewer"),
+      assertAccess("crm-call-evidence", args.evidenceId, "viewer"),
+    ]);
+    const db = getDb();
+    const [[run], [tracker], [evidence]] = await Promise.all([
+      db
+        .select()
+        .from(schema.crmSignalRuns)
+        .where(
+          and(
+            eq(schema.crmSignalRuns.id, args.runId),
+            accessFilter(schema.crmSignalRuns, schema.crmSignalRunShares),
+          ),
+        )
+        .limit(1),
+      db
+        .select()
+        .from(schema.crmSignalTrackers)
+        .where(
+          and(
+            eq(schema.crmSignalTrackers.id, args.trackerId),
+            accessFilter(
+              schema.crmSignalTrackers,
+              schema.crmSignalTrackerShares,
+            ),
+          ),
+        )
+        .limit(1),
+      db
+        .select()
+        .from(schema.crmCallEvidence)
+        .where(
+          and(
+            eq(schema.crmCallEvidence.id, args.evidenceId),
+            accessFilter(schema.crmCallEvidence, schema.crmCallEvidenceShares),
+          ),
+        )
+        .limit(1),
+    ]);
+    if (
+      !run ||
+      !tracker ||
+      !evidence ||
+      run.kind !== "smart" ||
+      run.recordId !== args.recordId ||
+      run.trackerId !== args.trackerId ||
+      tracker.kind !== "smart" ||
+      evidence.recordId !== args.recordId
+    )
+      signalTupleError(
+        "The signal run, tracker, evidence, and record do not form an accessible tuple.",
+      );
+    const source = evidence.quote.trim() || evidence.summary.trim();
+    if (!source.includes(args.quote))
+      throw new Error(
+        "The signal quote must be an exact substring of the stored bounded evidence excerpt.",
+      );
+    const idem = await crmSignalIdempotencyKey(
+      ctx,
+      args.recordId,
+      args.idempotencyKey,
+    );
+    const [existing] = await db
+      .select()
+      .from(schema.crmSignals)
+      .where(
+        and(
+          eq(schema.crmSignals.idempotencyKey, idem.key),
+          accessFilter(schema.crmSignals, schema.crmSignalShares),
+        ),
+      )
+      .limit(1);
+    if (existing) return existing;
+    const now = new Date().toISOString();
+    const id = crypto.randomUUID();
+    await db.transaction(async (tx) => {
+      await tx.insert(schema.crmSignals).values({
+        id,
+        runId: args.runId,
+        trackerId: args.trackerId,
+        recordId: args.recordId,
+        evidenceId: args.evidenceId,
+        kind: "moment",
+        label: tracker.name,
+        quote: args.quote,
+        speaker: evidence.speaker,
+        startSeconds: evidence.startSeconds,
+        endSeconds: evidence.endSeconds,
+        summary: "",
+        confidence: args.confidence,
+        detector: "agent",
+        model: args.model,
+        modelVersion: args.modelVersion ?? null,
+        reviewStatus: "unreviewed",
+        idempotencyKey: idem.key,
+        ...idem.scope,
+        createdAt: now,
+        updatedAt: now,
+      });
+      await tx
+        .update(schema.crmSignalRuns)
+        .set({
+          status: "completed",
+          model: args.model,
+          modelVersion: args.modelVersion ?? null,
+          completedAt: now,
+          updatedAt: now,
+        })
+        .where(eq(schema.crmSignalRuns.id, args.runId));
+    });
+    const [saved] = await db
+      .select()
+      .from(schema.crmSignals)
+      .where(eq(schema.crmSignals.id, id))
+      .limit(1);
+    if (!saved)
+      throw new Error("CRM signal could not be verified after saving.");
+    return saved;
+  },
+});

package/corpus/templates/crm/actions/restore-crm-dashboard-revision.ts

@@ -0,0 +1,23 @@
+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:
+    "Restore one revision of an access-scoped CRM dashboard. The restore is revision-aware and fails if the dashboard changed concurrently.",
+  schema: z.object({
+    id: z.string().trim().min(1).max(200),
+    revisionId: z.string().trim().min(1).max(200),
+  }),
+  run: async ({ id, revisionId }, ctx?: ActionRunContext) => {
+    const dashboard = await crmDashboardStore.restore(
+      id,
+      revisionId,
+      requireDashboardAccess(ctx),
+    );
+    if (!dashboard) throw new Error("CRM dashboard revision was not found.");
+    return dashboard;
+  },
+});

package/corpus/templates/crm/actions/review-crm-signal.ts

@@ -0,0 +1,31 @@
+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";
+
+export default defineAction({
+  description:
+    "Confirm, dismiss, or return one access-scoped CRM signal to the unreviewed queue.",
+  schema: z.object({
+    signalId: z.string().trim().min(1).max(128),
+    reviewStatus: z.enum(["unreviewed", "confirmed", "dismissed"]),
+  }),
+  run: async (args) => {
+    await assertAccess("crm-signal", args.signalId, "editor");
+    const now = new Date().toISOString();
+    await getDb()
+      .update(schema.crmSignals)
+      .set({ reviewStatus: args.reviewStatus, updatedAt: now })
+      .where(eq(schema.crmSignals.id, args.signalId));
+    const [saved] = await getDb()
+      .select()
+      .from(schema.crmSignals)
+      .where(eq(schema.crmSignals.id, args.signalId))
+      .limit(1);
+    if (!saved)
+      throw new Error("CRM signal could not be verified after review.");
+    return saved;
+  },
+});

package/corpus/templates/crm/actions/run-crm-saved-view-program.ts

@@ -0,0 +1,103 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { runDataProgram } from "@agent-native/core/data-programs";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { CRM_APP_ID } from "../server/lib/provider-api.js";
+import { isSafeCrmMutationFields } from "./_crm-action-utils.js";
+
+export default defineAction({
+  description:
+    "Run the data program linked to one access-scoped CRM saved view and return a bounded, sanitized preview.",
+  schema: z.object({
+    viewId: z.string().trim().min(1).max(128),
+  }),
+  agentTool: false,
+  toolCallable: false,
+  run: async ({ viewId }, ctx?: ActionRunContext) => {
+    if (!ctx?.userEmail) {
+      throw new Error("CRM data programs require an authenticated user.");
+    }
+    const [view] = await getDb()
+      .select({ dataProgramId: schema.crmSavedViews.dataProgramId })
+      .from(schema.crmSavedViews)
+      .where(
+        and(
+          eq(schema.crmSavedViews.id, viewId),
+          accessFilter(schema.crmSavedViews, schema.crmSavedViewShares),
+        ),
+      )
+      .limit(1);
+    if (!view?.dataProgramId) {
+      throw new Error("This CRM saved view has no data program.");
+    }
+    const result = await runDataProgram({
+      programId: view.dataProgramId,
+      appId: CRM_APP_ID,
+      params: {},
+      ctx: { userEmail: ctx.userEmail, orgId: ctx.orgId ?? null },
+      triggeredBy: "agent",
+    });
+    if (!result.ok) {
+      return {
+        ok: false as const,
+        code: result.error.code,
+        message: "The saved view data program could not run.",
+        ...(result.lastGoodRun
+          ? {
+              lastGoodRun: {
+                rowCount: result.lastGoodRun.rows.length,
+                columns: safeColumns(result.lastGoodRun.schema),
+                sampleRows: safeSampleRows(result.lastGoodRun.rows),
+                truncated: result.lastGoodRun.truncated,
+                asOfMs: result.lastGoodRun.asOfMs,
+              },
+            }
+          : {}),
+      };
+    }
+    return {
+      ok: true as const,
+      rowCount: result.rows.length,
+      columns: safeColumns(result.schema),
+      sampleRows: safeSampleRows(result.rows),
+      asOfMs: result.asOfMs,
+      cacheHit: result.cacheHit,
+      stale: result.stale,
+      truncated: result.truncated,
+    };
+  },
+});
+
+function safeColumns(columns: Array<{ name: string; type: string }>) {
+  return columns
+    .filter(
+      (column) =>
+        column.name.length <= 120 &&
+        isSafeCrmMutationFields({ [column.name]: "preview" }),
+    )
+    .slice(0, 12);
+}
+
+function safeSampleRows(rows: Array<Record<string, unknown>>) {
+  return rows.slice(0, 5).map((row) =>
+    Object.fromEntries(
+      Object.entries(row)
+        .filter(
+          ([fieldName, value]) =>
+            isSafeCrmMutationFields({ [fieldName]: value }) &&
+            (value === null ||
+              typeof value === "string" ||
+              typeof value === "number" ||
+              typeof value === "boolean"),
+        )
+        .slice(0, 12)
+        .map(([fieldName, value]) => [
+          fieldName,
+          typeof value === "string" ? value.slice(0, 500) : value,
+        ]),
+    ),
+  );
+}

package/corpus/templates/crm/actions/run-crm-signal-trackers.ts

@@ -0,0 +1,275 @@
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq, inArray } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { DEFAULT_CRM_DETECTORS } from "../server/lib/intelligence/default-detectors.js";
+import { runKeywordDetector } from "../server/lib/intelligence/keyword-detector.js";
+import { buildSmartDetectorPrompt } from "../server/lib/intelligence/smart-detector.js";
+import { buildCallEvidenceSummaryPrompt } from "../server/lib/intelligence/summary.js";
+import {
+  crmSignalIdempotencyKey,
+  evidenceExcerpts,
+  loadCrmSignalEvidence,
+} from "./_crm-signal-utils.js";
+
+export default defineAction({
+  description:
+    "Run deterministic keyword detectors and prepare bounded smart/summary requests for delegation through agent chat. Never calls an LLM or stores transcript bodies.",
+  schema: z.object({
+    recordId: z.string().trim().min(1).max(128),
+    evidenceIds: z.array(z.string().trim().min(1).max(128)).max(20).optional(),
+    trackerIds: z.array(z.string().trim().min(1).max(128)).max(20).optional(),
+    includeSummary: z.boolean().default(true),
+    idempotencyKey: z.string().trim().min(1).max(180),
+  }),
+  run: async (args, ctx) => {
+    const evidence = await loadCrmSignalEvidence({
+      recordId: args.recordId,
+      evidenceIds: args.evidenceIds,
+      role: "editor",
+    });
+    if (!evidence.length)
+      throw new Error(
+        "Attach bounded Clips call evidence before running signal detectors.",
+      );
+    const excerpts = evidenceExcerpts(evidence);
+    if (!excerpts.length)
+      throw new Error(
+        "The attached evidence has no bounded excerpt to analyze.",
+      );
+    await ensureDefaultTrackers(ctx);
+    const filters = [
+      eq(schema.crmSignalTrackers.enabled, true),
+      accessFilter(schema.crmSignalTrackers, schema.crmSignalTrackerShares),
+    ];
+    if (args.trackerIds?.length)
+      filters.push(inArray(schema.crmSignalTrackers.id, args.trackerIds));
+    const trackers = await getDb()
+      .select()
+      .from(schema.crmSignalTrackers)
+      .where(and(...filters))
+      .limit(20);
+    const now = new Date().toISOString();
+    const keywordRows: Array<typeof schema.crmSignals.$inferInsert> = [];
+    const delegated: Array<{
+      runId: string;
+      trackerId?: string;
+      kind: "smart" | "summary";
+      prompt: string;
+    }> = [];
+
+    for (const tracker of trackers) {
+      const runKey = await crmSignalIdempotencyKey(
+        ctx,
+        args.recordId,
+        `${args.idempotencyKey}:run:${tracker.id}`,
+      );
+      const [existingRun] = await getDb()
+        .select()
+        .from(schema.crmSignalRuns)
+        .where(
+          and(
+            eq(schema.crmSignalRuns.idempotencyKey, runKey.key),
+            accessFilter(schema.crmSignalRuns, schema.crmSignalRunShares),
+          ),
+        )
+        .limit(1);
+      if (existingRun) continue;
+      const runId = crypto.randomUUID();
+      if (tracker.kind === "keyword") {
+        const candidates = runKeywordDetector(
+          {
+            id: tracker.id,
+            name: tracker.name,
+            kind: "keyword",
+            keywords: safeKeywords(tracker.keywordsJson),
+          },
+          excerpts,
+        );
+        for (const candidate of candidates) {
+          const signalKey = await crmSignalIdempotencyKey(
+            ctx,
+            args.recordId,
+            `${args.idempotencyKey}:signal:${tracker.id}:${candidate.evidenceRef}:${candidate.quote}`,
+          );
+          keywordRows.push({
+            id: crypto.randomUUID(),
+            runId,
+            trackerId: tracker.id,
+            recordId: args.recordId,
+            evidenceId: candidate.evidenceRef,
+            kind: "moment",
+            label: tracker.name,
+            quote: candidate.quote,
+            speaker: candidate.speaker ?? null,
+            startSeconds: candidate.startSeconds,
+            endSeconds: candidate.endSeconds ?? null,
+            summary: "",
+            confidence: candidate.confidence,
+            detector: "keyword",
+            model: null,
+            modelVersion: null,
+            reviewStatus: "unreviewed",
+            idempotencyKey: signalKey.key,
+            ...signalKey.scope,
+            createdAt: now,
+            updatedAt: now,
+          });
+        }
+        await getDb().transaction(async (tx) => {
+          await tx.insert(schema.crmSignalRuns).values({
+            id: runId,
+            trackerId: tracker.id,
+            recordId: args.recordId,
+            kind: "keyword",
+            status: "completed",
+            evidenceCount: evidence.length,
+            idempotencyKey: runKey.key,
+            completedAt: now,
+            ...runKey.scope,
+            createdAt: now,
+            updatedAt: now,
+          });
+          const rows = keywordRows.filter((row) => row.runId === runId);
+          if (rows.length) await tx.insert(schema.crmSignals).values(rows);
+        });
+      } else {
+        const prompt = buildSmartDetectorPrompt(
+          {
+            id: tracker.id,
+            name: tracker.name,
+            description: tracker.description,
+            classifierPrompt: tracker.classifierPrompt,
+          },
+          excerpts,
+        );
+        if (!prompt) continue;
+        await getDb()
+          .insert(schema.crmSignalRuns)
+          .values({
+            id: runId,
+            trackerId: tracker.id,
+            recordId: args.recordId,
+            kind: "smart",
+            status: "queued",
+            evidenceCount: evidence.length,
+            idempotencyKey: runKey.key,
+            ...runKey.scope,
+            createdAt: now,
+            updatedAt: now,
+          });
+        delegated.push({ runId, trackerId: tracker.id, kind: "smart", prompt });
+      }
+    }
+
+    if (args.includeSummary) {
+      const runKey = await crmSignalIdempotencyKey(
+        ctx,
+        args.recordId,
+        `${args.idempotencyKey}:run:summary`,
+      );
+      const [existing] = await getDb()
+        .select({ id: schema.crmSignalRuns.id })
+        .from(schema.crmSignalRuns)
+        .where(
+          and(
+            eq(schema.crmSignalRuns.idempotencyKey, runKey.key),
+            accessFilter(schema.crmSignalRuns, schema.crmSignalRunShares),
+          ),
+        )
+        .limit(1);
+      if (!existing) {
+        const runId = crypto.randomUUID();
+        const prompt = buildCallEvidenceSummaryPrompt(
+          `CRM record ${args.recordId}`,
+          excerpts,
+        );
+        if (prompt) {
+          await getDb()
+            .insert(schema.crmSignalRuns)
+            .values({
+              id: runId,
+              trackerId: null,
+              recordId: args.recordId,
+              kind: "summary",
+              status: "queued",
+              evidenceCount: evidence.length,
+              idempotencyKey: runKey.key,
+              ...runKey.scope,
+              createdAt: now,
+              updatedAt: now,
+            });
+          delegated.push({ runId, kind: "summary", prompt });
+        }
+      }
+    }
+
+    for (const request of delegated) {
+      await writeAppState(`crm-signal-agent-request-${request.runId}`, {
+        runId: request.runId,
+        recordId: args.recordId,
+        trackerId: request.trackerId,
+        kind: request.kind,
+        evidenceIds: evidence.map((item) => item.id),
+      });
+    }
+    return {
+      keywordSignalsCreated: keywordRows.length,
+      delegatedRequests: delegated,
+    };
+  },
+});
+
+function safeKeywords(value: string): string[] {
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return Array.isArray(parsed)
+      ? parsed
+          .filter((item): item is string => typeof item === "string")
+          .slice(0, 40)
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+async function ensureDefaultTrackers(
+  ctx: Parameters<typeof crmSignalIdempotencyKey>[0],
+) {
+  const db = getDb();
+  const [existing] = await db
+    .select({ id: schema.crmSignalTrackers.id })
+    .from(schema.crmSignalTrackers)
+    .where(
+      accessFilter(schema.crmSignalTrackers, schema.crmSignalTrackerShares),
+    )
+    .limit(1);
+  if (existing) return;
+  const now = new Date().toISOString();
+  for (const detector of DEFAULT_CRM_DETECTORS) {
+    const identity = await crmSignalIdempotencyKey(
+      ctx,
+      "defaults",
+      detector.id,
+    );
+    await db
+      .insert(schema.crmSignalTrackers)
+      .values({
+        id: `default-${identity.key.slice(-32)}`,
+        name: detector.name,
+        description: detector.description,
+        kind: detector.kind,
+        keywordsJson: JSON.stringify(detector.keywords ?? []),
+        classifierPrompt: detector.classifierPrompt ?? "",
+        enabled: true,
+        isDefault: true,
+        ...identity.scope,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoNothing();
+  }
+}

package/corpus/templates/crm/actions/run.ts

@@ -0,0 +1,11 @@
+import { initDataPrograms } from "@agent-native/core/data-programs";
+import { runScript } from "@agent-native/core/scripts";
+
+import getCrmPipelineData from "./get-crm-pipeline-data.js";
+
+initDataPrograms({
+  appId: "crm",
+  getActions: () => ({ "get-crm-pipeline-data": getCrmPipelineData }),
+});
+
+runScript();

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

@@ -0,0 +1,51 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  crmDashboardStore,
+  type CrmDashboardConfig,
+} from "../server/db/index.js";
+import { requireDashboardAccess } from "./_crm-dashboard.js";
+
+const configSchema = z.object({
+  version: z.literal(1),
+  panels: z
+    .array(
+      z.object({
+        id: z.string().trim().min(1).max(120),
+        title: z.string().trim().min(1).max(160),
+        source: z.literal("program"),
+        query: z.string().trim().min(1).max(2_000),
+        chartType: z.enum(["metric", "bar", "table"]),
+      }),
+    )
+    .min(1)
+    .max(12)
+    .refine(
+      (panels) =>
+        new Set(panels.map((panel) => panel.id)).size === panels.length,
+      "Dashboard panel IDs must be unique.",
+    ),
+});
+
+export default defineAction({
+  description:
+    "Create or update an access-scoped CRM pipeline dashboard. Pass expectedUpdatedAt to reject an overwrite when the dashboard changed since it was read.",
+  schema: z.object({
+    id: z.string().trim().min(1).max(200),
+    title: z.string().trim().min(1).max(160),
+    config: configSchema,
+    expectedUpdatedAt: z.string().datetime().optional(),
+  }),
+  run: ({ id, title, config, expectedUpdatedAt }, ctx?: ActionRunContext) =>
+    crmDashboardStore.write(
+      {
+        id,
+        kind: "pipeline",
+        title,
+        config: config as CrmDashboardConfig,
+        expectedUpdatedAt,
+      },
+      requireDashboardAccess(ctx),
+    ),
+});