@agent-native/core 0.114.16 → 0.115.1

package/corpus/templates/crm/actions/manage-crm-task.ts

@@ -0,0 +1,132 @@
+import { defineAction } from "@agent-native/core/action";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+
+export default defineAction({
+  description:
+    "Create or update a local CRM follow-up task. Mirrored provider tasks remain read-only in this phase so they cannot be changed without an explicit provider proposal.",
+  schema: z
+    .object({
+      taskId: z.string().trim().min(1).max(128).optional(),
+      recordId: z.string().trim().min(1).max(128).optional(),
+      title: z.string().trim().min(1).max(300).optional(),
+      description: z.string().trim().max(2_000).optional(),
+      status: z.enum(["open", "done", "cancelled"]).optional(),
+      dueAt: z.string().datetime({ offset: true }).optional(),
+      assignedTo: z.string().trim().max(240).optional(),
+    })
+    .superRefine((value, issue) => {
+      if (!value.taskId && !value.title) {
+        issue.addIssue({
+          code: "custom",
+          message: "title is required when creating a task",
+          path: ["title"],
+        });
+      }
+    }),
+  audit: {
+    target: (_args, result) => {
+      const task = result as {
+        id: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-task",
+        id: task.id,
+        ownerEmail: task.ownerEmail,
+        orgId: task.orgId,
+        visibility: task.visibility,
+      };
+    },
+    summary: (args) =>
+      args.taskId
+        ? `Updated CRM task ${args.taskId}`
+        : `Created CRM task ${args.title}`,
+  },
+  run: async (args, ctx) => {
+    const db = getDb();
+    const now = new Date().toISOString();
+    if (args.taskId) {
+      await assertAccess("crm-task", args.taskId, "editor");
+      const [task] = await db
+        .select()
+        .from(schema.crmTasks)
+        .where(eq(schema.crmTasks.id, args.taskId))
+        .limit(1);
+      if (!task) throw new Error("CRM task was not found.");
+      if (task.authority !== "local") {
+        throw new Error(
+          "This is a mirrored provider task. Provider task writeback is not available in the initial release; create a CRM proposal or complete it upstream.",
+        );
+      }
+      if (args.recordId && args.recordId !== task.recordId) {
+        await assertAccess("crm-record", args.recordId, "editor");
+      }
+      await db
+        .update(schema.crmTasks)
+        .set({
+          ...(args.recordId !== undefined ? { recordId: args.recordId } : {}),
+          ...(args.title !== undefined ? { title: args.title } : {}),
+          ...(args.description !== undefined
+            ? { description: args.description }
+            : {}),
+          ...(args.status !== undefined ? { status: args.status } : {}),
+          ...(args.dueAt !== undefined ? { dueAt: args.dueAt } : {}),
+          ...(args.assignedTo !== undefined
+            ? { assignedTo: args.assignedTo }
+            : {}),
+          ...(args.status === "done" ? { completedAt: now } : {}),
+          ...(args.status && args.status !== "done"
+            ? { completedAt: null }
+            : {}),
+          updatedAt: now,
+        })
+        .where(eq(schema.crmTasks.id, args.taskId));
+      const [updated] = await db
+        .select()
+        .from(schema.crmTasks)
+        .where(eq(schema.crmTasks.id, args.taskId))
+        .limit(1);
+      if (!updated)
+        throw new Error("CRM task could not be verified after updating.");
+      return updated;
+    }
+
+    if (args.recordId)
+      await assertAccess("crm-record", args.recordId, "editor");
+    const scope = requireCrmScope(ctx);
+    const id = crypto.randomUUID();
+    await db.insert(schema.crmTasks).values({
+      id,
+      recordId: args.recordId ?? null,
+      title: args.title!,
+      description: args.description ?? "",
+      status: args.status ?? "open",
+      dueAt: args.dueAt ?? null,
+      assignedTo: args.assignedTo ?? null,
+      authority: "local",
+      completedAt: args.status === "done" ? now : null,
+      ...scope,
+      createdAt: now,
+      updatedAt: now,
+    });
+    const [task] = await db
+      .select()
+      .from(schema.crmTasks)
+      .where(
+        and(
+          eq(schema.crmTasks.id, id),
+          eq(schema.crmTasks.ownerEmail, scope.ownerEmail),
+        ),
+      )
+      .limit(1);
+    if (!task) throw new Error("CRM task could not be verified after saving.");
+    return task;
+  },
+});

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

@@ -0,0 +1,63 @@
+import { defineAction } from "@agent-native/core/action";
+import { writeAppStateForCurrentTab } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+const viewSchema = z.enum([
+  "work",
+  "account",
+  "person",
+  "opportunity",
+  "record",
+  "tasks",
+  "proposals",
+  "views",
+  "dashboard",
+  "ask",
+  "setup",
+  "settings",
+]);
+
+const paths = {
+  work: "/",
+  account: "/accounts",
+  person: "/people",
+  opportunity: "/opportunities",
+  tasks: "/tasks",
+  proposals: "/proposals",
+  views: "/views",
+  dashboard: "/dashboard",
+  ask: "/ask",
+  setup: "/setup",
+  settings: "/settings",
+} as const;
+
+export default defineAction({
+  description:
+    "Navigate the CRM UI to work, records, tasks, proposals, saved views, Ask CRM, setup, or settings.",
+  schema: z.object({
+    view: viewSchema,
+    recordId: z.string().trim().min(1).max(200).optional(),
+    viewId: z.string().trim().min(1).max(200).optional(),
+    dashboardId: z.string().trim().min(1).max(200).optional(),
+    query: z.string().trim().max(200).optional(),
+    settingsSection: z.enum(["intelligence"]).optional(),
+  }),
+  http: false,
+  run: async (args) => {
+    if (args.view === "record" && !args.recordId) {
+      throw new Error("recordId is required when navigating to a CRM record.");
+    }
+    const basePath =
+      args.view === "record"
+        ? `/records/${encodeURIComponent(args.recordId!)}`
+        : args.view === "settings" && args.settingsSection
+          ? `/settings/${args.settingsSection}`
+          : paths[args.view];
+    const path =
+      args.view === "dashboard" && args.dashboardId
+        ? `${basePath}?id=${encodeURIComponent(args.dashboardId)}`
+        : basePath;
+    await writeAppStateForCurrentTab("navigate", { ...args, path });
+    return { navigatingTo: path };
+  },
+});

package/corpus/templates/crm/actions/provider-api-catalog.ts

@@ -0,0 +1,22 @@
+import { createProviderApiCatalogAction } from "@agent-native/core/provider-api/actions/provider-api";
+import { z } from "zod";
+
+import {
+  CRM_PROVIDER_API_IDS,
+  getCrmProviderApiRuntime,
+} from "../server/lib/provider-api.js";
+
+const ProviderSchema = z.enum(CRM_PROVIDER_API_IDS);
+
+export default createProviderApiCatalogAction(getCrmProviderApiRuntime(), {
+  description:
+    "List the raw HubSpot and Salesforce API capabilities available through CRM's granted workspace connections. Use before provider-api-request when a CRM convenience action cannot express an endpoint, filter, custom object, pagination mode, or API version. Returns metadata and examples, never secret values.",
+  schema: z.object({
+    provider: ProviderSchema.optional().describe(
+      "Optional provider id to inspect: hubspot or salesforce.",
+    ),
+  }),
+  http: { method: "GET" },
+  guidance:
+    "CRM actions are convenience workflows, not a provider capability limit. For an exact HubSpot or Salesforce endpoint, inspect its catalog and docs before provider-api-request. For broad work, stage a bounded paginated result, reduce it with query-staged-dataset or a data program, and report the scope, row count, pagination status, truncation, and gaps.",
+});

package/corpus/templates/crm/actions/provider-api-docs.ts

@@ -0,0 +1,54 @@
+import { createProviderApiDocsAction } from "@agent-native/core/provider-api/actions/provider-api";
+import { z } from "zod";
+
+import {
+  CRM_PROVIDER_API_IDS,
+  getCrmProviderApiRuntime,
+} from "../server/lib/provider-api.js";
+
+const ProviderSchema = z.enum(CRM_PROVIDER_API_IDS);
+const BooleanFromQuerySchema = z.preprocess(
+  (value) => (typeof value === "string" ? value === "true" : value),
+  z.boolean(),
+);
+
+export default createProviderApiDocsAction(getCrmProviderApiRuntime(), {
+  description:
+    "Inspect HubSpot or Salesforce API documentation before an exact provider-api-request when the endpoint, object schema, field, filter operator, relationship, or pagination contract is uncertain.",
+  schema: z.object({
+    provider: ProviderSchema.describe("Provider whose API docs to inspect."),
+    url: z
+      .string()
+      .url()
+      .optional()
+      .describe(
+        "Optional public provider docs/spec URL. The provider catalog returns curated starting URLs.",
+      ),
+    maxBytes: z.coerce
+      .number()
+      .int()
+      .min(1_000)
+      .max(4 * 1024 * 1024)
+      .optional(),
+    maxChars: z.coerce.number().int().min(1).max(200_000).optional(),
+    responseMode: z
+      .enum(["auto", "raw", "text", "markdown", "links", "metadata", "matches"])
+      .optional(),
+    extract: z.enum(["readability", "all-visible", "none"]).optional(),
+    includeLinks: BooleanFromQuerySchema.optional(),
+    search: z
+      .object({
+        query: z.union([z.string(), z.array(z.string())]).optional(),
+        queries: z.array(z.string()).optional(),
+        terms: z.array(z.string()).optional(),
+        regex: z.string().optional(),
+        regexFlags: z.string().optional(),
+        source: z.enum(["extracted", "raw"]).optional(),
+        maxMatches: z.coerce.number().int().min(1).max(500).optional(),
+        contextChars: z.coerce.number().int().min(0).max(1_000).optional(),
+        caseSensitive: BooleanFromQuerySchema.optional(),
+      })
+      .optional(),
+  }),
+  http: { method: "GET" },
+});

package/corpus/templates/crm/actions/provider-api-request.ts

@@ -0,0 +1,92 @@
+import { createProviderApiRequestAction } from "@agent-native/core/provider-api/actions/provider-api";
+import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+import {
+  CRM_APP_ID,
+  CRM_PROVIDER_API_IDS,
+  getCrmProviderApiRuntime,
+} from "../server/lib/provider-api.js";
+
+const ProviderSchema = z.enum(CRM_PROVIDER_API_IDS);
+const MethodSchema = z.enum(["GET", "HEAD"]);
+
+const PaginationSchema = z
+  .object({
+    nextCursorPath: z.string().optional(),
+    cursorParam: z.string().optional(),
+    pageParam: z.string().optional(),
+    startPage: z.coerce.number().int().optional(),
+    offsetParam: z.string().optional(),
+    pageSize: z.coerce.number().int().min(1).optional(),
+    maxPages: z.coerce.number().int().min(1).max(200).optional(),
+  })
+  .optional();
+
+export default createProviderApiRequestAction(getCrmProviderApiRuntime(), {
+  description:
+    "Make an exact read-only authenticated HubSpot or Salesforce GET or HEAD request through a CRM-granted workspace connection. This is the flexible escape hatch for custom object, field, relationship, pagination, and API-version reads that CRM convenience actions do not model. It is host-constrained, access-scoped to the granted connection, and redacts secrets. Provider writes must use revision-aware CRM proposals, never this action. Use stageAs for large results instead of returning raw provider payloads to chat.",
+  schema: z
+    .object({
+      provider: ProviderSchema.describe("CRM provider: hubspot or salesforce."),
+      method: MethodSchema.default("GET"),
+      path: z
+        .string()
+        .min(1)
+        .describe(
+          "Provider API path, or a full URL on the selected connection's allowed provider host.",
+        ),
+      query: z.unknown().optional(),
+      headers: z.record(z.string(), z.unknown()).optional(),
+      auth: z.enum(["default", "none"]).default("default"),
+      connectionId: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe(
+          "Granted workspace connection id. Required for Salesforce so its actor-bound token and instance URL stay coupled.",
+        ),
+      timeoutMs: z.coerce.number().int().min(1_000).max(120_000).optional(),
+      maxBytes: z.coerce
+        .number()
+        .int()
+        .min(1_000)
+        .max(4 * 1024 * 1024)
+        .optional(),
+      stageAs: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Store response items as a caller-scoped scratch dataset and return a compact summary.",
+        ),
+      itemsPath: z.string().optional(),
+      pagination: PaginationSchema.describe(
+        "Server-side query-string pagination for a staged response. Use the provider's catalog/docs to choose its cursor fields.",
+      ),
+      saveToFile: z.string().optional(),
+      fetchAllPages: z
+        .object({
+          cursorPath: z.string(),
+          cursorParam: z.string().optional(),
+          itemsPath: z.string().optional(),
+          maxPages: z.coerce.number().int().min(1).max(50).optional(),
+        })
+        .optional(),
+    })
+    .superRefine((value, ctx) => {
+      if (value.provider === "salesforce" && !value.connectionId) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connectionId"],
+          message:
+            "Salesforce provider reads require the granted workspace connection id.",
+        });
+      }
+    }),
+  appId: CRM_APP_ID,
+  getOwnerEmail: () => getCredentialContext()?.userEmail ?? null,
+  http: false,
+  toolCallable: false,
+});

package/corpus/templates/crm/actions/query-staged-dataset.ts

@@ -0,0 +1,44 @@
+import { createQueryStagedDatasetAction } from "@agent-native/core/provider-api/actions/staged-datasets";
+import { z } from "zod";
+
+import { CRM_APP_ID } from "../server/lib/provider-api.js";
+
+const WhereSchema = z.object({
+  column: z.string().min(1),
+  op: z.enum([
+    "equals",
+    "not_equals",
+    "contains",
+    "not_contains",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "exists",
+    "not_exists",
+  ]),
+  value: z.unknown().optional(),
+});
+
+const AggregateSchema = z.object({
+  column: z.string().min(1),
+  op: z.enum(["sum", "avg", "count", "min", "max", "count_distinct"]),
+  as: z.string().optional(),
+});
+
+export default createQueryStagedDatasetAction({
+  description:
+    "Filter, project, sort, or aggregate a caller-scoped staged CRM provider dataset without re-fetching the provider. For exhaustive CRM analysis, stage every bounded page first and report the dataset's source scope, row count, pagination status, truncation, and gaps.",
+  schema: z.object({
+    datasetId: z.string().min(1),
+    where: z.array(WhereSchema).optional(),
+    groupBy: z.array(z.string().min(1)).optional(),
+    aggregate: z.array(AggregateSchema).optional(),
+    select: z.array(z.string().min(1)).optional(),
+    orderBy: z.string().optional(),
+    orderDir: z.enum(["asc", "desc"]).optional(),
+    limit: z.coerce.number().int().min(1).max(10_000).optional(),
+  }),
+  http: false,
+  appId: CRM_APP_ID,
+});

package/corpus/templates/crm/actions/record-crm-call-insight.ts

@@ -0,0 +1,160 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq, inArray } 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";
+
+const insightSchema = z.object({
+  evidenceId: z.string().trim().min(1).max(128),
+  kind: z.enum(["call-summary", "next-step"]),
+  label: z.string().trim().min(1).max(120),
+  summary: z.string().trim().min(1).max(1_200).refine(isSafeCrmEvidenceExcerpt),
+  quote: z
+    .string()
+    .trim()
+    .max(1_200)
+    .refine(isSafeCrmEvidenceExcerpt)
+    .optional(),
+  quoteSeconds: z.coerce.number().finite().min(0).max(86_400),
+});
+
+export default defineAction({
+  description:
+    "Atomically record a bounded, evidence-cited call recap or next-step set produced through agent chat. No transcript body or raw model response is accepted.",
+  schema: z.object({
+    runId: z.string().trim().min(1).max(128),
+    recordId: z.string().trim().min(1).max(128),
+    insights: z.array(insightSchema).min(1).max(20),
+    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"),
+      ...args.insights.map((item) =>
+        assertAccess("crm-call-evidence", item.evidenceId, "viewer"),
+      ),
+    ]);
+    const db = getDb();
+    const [run] = await db
+      .select()
+      .from(schema.crmSignalRuns)
+      .where(
+        and(
+          eq(schema.crmSignalRuns.id, args.runId),
+          accessFilter(schema.crmSignalRuns, schema.crmSignalRunShares),
+        ),
+      )
+      .limit(1);
+    const evidenceIds = [
+      ...new Set(args.insights.map((item) => item.evidenceId)),
+    ];
+    const evidence = await db
+      .select()
+      .from(schema.crmCallEvidence)
+      .where(
+        and(
+          inArray(schema.crmCallEvidence.id, evidenceIds),
+          accessFilter(schema.crmCallEvidence, schema.crmCallEvidenceShares),
+        ),
+      )
+      .limit(20);
+    if (
+      !run ||
+      run.kind !== "summary" ||
+      run.recordId !== args.recordId ||
+      evidence.length !== evidenceIds.length ||
+      evidence.some((item) => item.recordId !== args.recordId)
+    )
+      signalTupleError(
+        "The summary run, evidence, and record do not form an accessible tuple.",
+      );
+    const byId = new Map(evidence.map((item) => [item.id, item]));
+    const now = new Date().toISOString();
+    const rows: Array<typeof schema.crmSignals.$inferInsert> = [];
+    for (const [index, item] of args.insights.entries()) {
+      const source = byId.get(item.evidenceId)!;
+      const excerpt = source.quote.trim() || source.summary.trim();
+      if (item.quote && !excerpt.includes(item.quote))
+        throw new Error(
+          "Every insight quote must be an exact substring of its stored bounded evidence excerpt.",
+        );
+      const start = source.startSeconds ?? 0;
+      if (
+        item.quoteSeconds < start ||
+        (source.endSeconds !== null && item.quoteSeconds > source.endSeconds)
+      )
+        throw new Error(
+          "Every insight timestamp must fall inside its evidence excerpt.",
+        );
+      const idem = await crmSignalIdempotencyKey(
+        ctx,
+        args.recordId,
+        `${args.idempotencyKey}:${index}`,
+      );
+      rows.push({
+        id: crypto.randomUUID(),
+        runId: args.runId,
+        trackerId: null,
+        recordId: args.recordId,
+        evidenceId: item.evidenceId,
+        kind: item.kind,
+        label: item.label,
+        quote: item.quote ?? "",
+        speaker: source.speaker,
+        startSeconds: item.quoteSeconds,
+        endSeconds: source.endSeconds,
+        summary: item.summary,
+        confidence: 100,
+        detector: "agent",
+        model: args.model,
+        modelVersion: args.modelVersion ?? null,
+        reviewStatus: "unreviewed",
+        idempotencyKey: idem.key,
+        ...idem.scope,
+        createdAt: now,
+        updatedAt: now,
+      });
+    }
+    const existing = await db
+      .select({ key: schema.crmSignals.idempotencyKey })
+      .from(schema.crmSignals)
+      .where(
+        and(
+          inArray(
+            schema.crmSignals.idempotencyKey,
+            rows.map((row) => row.idempotencyKey),
+          ),
+          accessFilter(schema.crmSignals, schema.crmSignalShares),
+        ),
+      );
+    const existingKeys = new Set(existing.map((item) => item.key));
+    const pending = rows.filter((row) => !existingKeys.has(row.idempotencyKey));
+    await db.transaction(async (tx) => {
+      if (pending.length) await tx.insert(schema.crmSignals).values(pending);
+      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));
+    });
+    return {
+      created: pending.length,
+      replayed: rows.length - pending.length,
+      signalIds: pending.map((row) => row.id),
+    };
+  },
+});