@agent-native/core 0.114.16 → 0.115.3

package/src/connections/catalog.ts

@@ -13,6 +13,7 @@ export type WorkspaceConnectionTemplateUse =
   | "calendar"
   | "clips"
   | "content"
+  | "crm"
   | "design"
   | "dispatch"
   | "forms"
@@ -27,6 +28,7 @@ export type WorkspaceConnectionProviderId =
   | "gmail"
   | "google_drive"
   | "hubspot"
+  | "salesforce"
   | "jira"
   | "sentry"
   | "granola"
@@ -239,7 +241,24 @@ export const WORKSPACE_CONNECTION_PROVIDERS = [
       ],
     },
     capabilities: ["search", "import", "crm"],
-    recommendedTemplateUses: ["analytics", "brain", "mail", "dispatch"],
+    recommendedTemplateUses: ["analytics", "brain", "crm", "mail", "dispatch"],
+  }),
+  defineWorkspaceConnectionProvider({
+    id: "salesforce",
+    label: "Salesforce",
+    description:
+      "CRM accounts, contacts, opportunities, custom objects, and activity history for customer-aware apps.",
+    credentialKeys: [],
+    oauth: {
+      provider: "salesforce",
+      authorizationUrl:
+        "https://login.salesforce.com/services/oauth2/authorize",
+      tokenUrl: "https://login.salesforce.com/services/oauth2/token",
+      refreshUrl: "https://login.salesforce.com/services/oauth2/token",
+      scopes: ["api", "refresh_token", "id"],
+    },
+    capabilities: ["search", "import", "crm"],
+    recommendedTemplateUses: ["analytics", "brain", "crm", "dispatch"],
   }),
   defineWorkspaceConnectionProvider({
     id: "jira",

package/src/connections/reader.ts

@@ -506,6 +506,71 @@ export const PROVIDER_READERS = [
     notes:
       "Templates define object allow-lists and property projections; core only documents the reader shape.",
   }),
+  defineProviderReader({
+    providerId: "salesforce",
+    label: "Salesforce reader",
+    description:
+      "Normalized metadata for CRM object lookup through template-owned Salesforce integrations.",
+    implementationStatus: "template-owned",
+    credentialKeys: providerCredentialKeys("salesforce"),
+    requiredCredentialKeys: requiredCredentialKeys("salesforce"),
+    capabilities: [
+      {
+        capability: "search",
+        label: "CRM search",
+        description:
+          "Search Salesforce CRM records with provider-native SOQL or object filters.",
+      },
+      {
+        capability: "crm",
+        label: "CRM retrieval",
+        description:
+          "Read Salesforce standard and custom CRM objects when a template owns object mapping.",
+      },
+    ],
+    operations: [
+      operation(
+        "search",
+        "Search Salesforce CRM",
+        "Find CRM records matching text, SOQL, or provider-native filters.",
+        "template-owned",
+        [
+          ...searchParameters,
+          {
+            name: "objectType",
+            type: "string",
+            description:
+              "Optional Salesforce object API name such as Account, Contact, Opportunity, or a custom object.",
+          },
+        ],
+      ),
+      operation(
+        "get",
+        "Get Salesforce CRM object",
+        "Load one Salesforce CRM record by object API name and id.",
+        "template-owned",
+        [
+          ...getParameters,
+          {
+            name: "objectType",
+            type: "string",
+            required: true,
+            description:
+              "Salesforce object API name such as Account, Contact, Opportunity, or a custom object.",
+          },
+        ],
+      ),
+      operation(
+        "listRecent",
+        "List recent Salesforce CRM objects",
+        "List recently updated CRM records visible to the connected Salesforce user.",
+        "template-owned",
+        listRecentParameters,
+      ),
+    ],
+    notes:
+      "Templates define object allow-lists, field projections, and API-version selection; core only documents the reader shape.",
+  }),
   defineProviderReader({
     providerId: "gmail",
     label: "Gmail reader",

package/src/dashboard-storage/index.ts

@@ -0,0 +1,27 @@
+export {
+  createDashboardStorageSchema,
+  type DashboardStorageSchema,
+  type DashboardStorageSchemaOptions,
+} from "./schema.js";
+export {
+  createDashboardStorage,
+  DashboardStorageConflictError,
+  type DashboardRecord,
+  type DashboardRevisionRecord,
+  type DashboardStorageOptions,
+  type DashboardWriteInput,
+} from "./store.js";
+export {
+  createPanelSourceResolverRegistry,
+  createProgramPanelSourceResolver,
+  parseProgramPanelDescriptor,
+  type DashboardPanelColumn,
+  type PanelSourceFailure,
+  type PanelSourceRequest,
+  type PanelSourceResolver,
+  type PanelSourceResolverRegistry,
+  type PanelSourceResponse,
+  type PanelSourceResult,
+  type ProgramPanelContext,
+  type ProgramPanelDescriptor,
+} from "./panel-source.js";

package/src/dashboard-storage/panel-source.ts

@@ -0,0 +1,168 @@
+import { runDataProgram } from "../data-programs/index.js";
+
+export interface DashboardPanelColumn {
+  name: string;
+  type: string;
+}
+
+export interface PanelSourceRequest<TSource extends string = string> {
+  source: TSource;
+  query: string;
+}
+
+export interface PanelSourceResult {
+  rows: Record<string, unknown>[];
+  schema?: DashboardPanelColumn[];
+  truncated?: boolean;
+  bytesProcessed?: number;
+}
+
+export interface PanelSourceFailure {
+  error: string;
+  message?: string;
+}
+
+export type PanelSourceResponse = PanelSourceResult | PanelSourceFailure;
+
+export interface PanelSourceResolver<
+  TSource extends string = string,
+  TContext = unknown,
+> {
+  source: TSource;
+  resolve(
+    request: PanelSourceRequest<TSource>,
+    context: TContext,
+  ): Promise<PanelSourceResponse>;
+}
+
+export interface PanelSourceResolverRegistry<
+  TSource extends string = string,
+  TContext = unknown,
+> {
+  readonly sources: readonly TSource[];
+  resolve(
+    request: PanelSourceRequest<TSource>,
+    context: TContext,
+  ): Promise<PanelSourceResponse>;
+}
+
+export function createPanelSourceResolverRegistry<
+  TSource extends string = string,
+  TContext = unknown,
+>(options: {
+  resolvers: readonly PanelSourceResolver<TSource, TContext>[];
+}): PanelSourceResolverRegistry<TSource, TContext> {
+  const resolvers = new Map<TSource, PanelSourceResolver<TSource, TContext>>();
+  for (const resolver of options.resolvers) {
+    const source = resolver.source.trim() as TSource;
+    if (!source) throw new Error("Panel source resolver requires a source.");
+    if (resolvers.has(source)) {
+      throw new Error(`Duplicate panel source resolver: ${source}`);
+    }
+    resolvers.set(source, resolver);
+  }
+
+  return {
+    sources: [...resolvers.keys()],
+    async resolve(request, context) {
+      const resolver = resolvers.get(request.source);
+      if (!resolver) {
+        throw new Error(
+          `Unsupported dashboard panel source: ${request.source}`,
+        );
+      }
+      return resolver.resolve(request, context);
+    },
+  };
+}
+
+export interface ProgramPanelContext {
+  userEmail: string;
+  orgId?: string | null;
+}
+
+export interface ProgramPanelDescriptor {
+  programId: string;
+  params?: Record<string, unknown>;
+}
+
+export interface ProgramPanelRunResult {
+  ok: boolean;
+  rows?: Record<string, unknown>[];
+  schema?: DashboardPanelColumn[];
+  truncated?: boolean;
+  lastGoodRun?: {
+    rows: Record<string, unknown>[];
+    schema: DashboardPanelColumn[];
+    truncated?: boolean;
+  };
+  error?: { code: string; message: string };
+}
+
+export function parseProgramPanelDescriptor(
+  query: string,
+): ProgramPanelDescriptor {
+  let value: unknown;
+  try {
+    value = JSON.parse(query);
+  } catch {
+    throw new Error("Program panel query must be a JSON object.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Program panel query must be a JSON object.");
+  }
+  const descriptor = value as Record<string, unknown>;
+  if (
+    typeof descriptor.programId !== "string" ||
+    !descriptor.programId.trim()
+  ) {
+    throw new Error("Program panel query requires a programId.");
+  }
+  const params =
+    descriptor.params &&
+    typeof descriptor.params === "object" &&
+    !Array.isArray(descriptor.params)
+      ? (descriptor.params as Record<string, unknown>)
+      : undefined;
+  return { programId: descriptor.programId.trim(), params };
+}
+
+export function createProgramPanelSourceResolver(options: {
+  appId: string;
+  run?: (args: {
+    programId: string;
+    appId: string;
+    params?: Record<string, unknown>;
+    ctx: { userEmail: string; orgId: string | null };
+    triggeredBy: "panel_view";
+  }) => Promise<ProgramPanelRunResult>;
+}): PanelSourceResolver<"program", ProgramPanelContext> {
+  const run = options.run ?? runDataProgram;
+  return {
+    source: "program",
+    async resolve(request, context) {
+      const descriptor = parseProgramPanelDescriptor(request.query);
+      const result = await run({
+        programId: descriptor.programId,
+        appId: options.appId,
+        params: descriptor.params,
+        ctx: {
+          userEmail: context.userEmail,
+          orgId: context.orgId ?? null,
+        },
+        triggeredBy: "panel_view",
+      });
+      if (result.ok) {
+        return {
+          rows: result.rows ?? [],
+          schema: result.schema,
+          truncated: result.truncated,
+        };
+      }
+      if (result.lastGoodRun) return result.lastGoodRun;
+      throw new Error(
+        `${result.error?.code ?? "program_failed"}: ${result.error?.message ?? "Data program failed."}`,
+      );
+    },
+  };
+}

package/src/dashboard-storage/schema.ts

@@ -0,0 +1,62 @@
+import {
+  createSharesTable,
+  index,
+  now,
+  ownableColumns,
+  table,
+  text,
+} from "../db/schema.js";
+
+export interface DashboardStorageSchemaOptions {
+  dashboardsTable?: string;
+  revisionsTable?: string;
+  sharesTable?: string;
+}
+
+export function createDashboardStorageSchema(
+  options: DashboardStorageSchemaOptions = {},
+) {
+  const dashboardsTable = options.dashboardsTable ?? "dashboards";
+  const revisionsTable = options.revisionsTable ?? "dashboard_revisions";
+  const sharesTable = options.sharesTable ?? "dashboard_shares";
+
+  const dashboards = table(dashboardsTable, {
+    id: text("id").primaryKey(),
+    kind: text("kind").notNull(),
+    title: text("title").notNull().default("Untitled"),
+    config: text("config").notNull(),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+    updatedBy: text("updated_by"),
+    archivedAt: text("archived_at"),
+    ...ownableColumns(),
+  });
+
+  const dashboardShares = createSharesTable(sharesTable);
+
+  const dashboardRevisions = table(
+    revisionsTable,
+    {
+      id: text("id").primaryKey(),
+      dashboardId: text("dashboard_id").notNull(),
+      kind: text("kind").notNull(),
+      title: text("title").notNull(),
+      config: text("config").notNull(),
+      createdAt: text("created_at").notNull().default(now()),
+      createdBy: text("created_by"),
+      ...ownableColumns(),
+    },
+    (revision) => ({
+      dashboardCreatedIdx: index(`${revisionsTable}_dashboard_created_idx`).on(
+        revision.dashboardId,
+        revision.createdAt,
+      ),
+    }),
+  );
+
+  return { dashboards, dashboardRevisions, dashboardShares };
+}
+
+export type DashboardStorageSchema = ReturnType<
+  typeof createDashboardStorageSchema
+>;

package/src/dashboard-storage/store.ts

@@ -0,0 +1,333 @@
+import { randomUUID } from "node:crypto";
+
+import { and, desc, eq, inArray, isNotNull, isNull } from "drizzle-orm";
+
+import type { AccessContext } from "../sharing/access.js";
+import { accessFilter, assertAccess } from "../sharing/access.js";
+import { registerShareableResource } from "../sharing/registry.js";
+import type { DashboardStorageSchema } from "./schema.js";
+
+export interface DashboardRecord<
+  TKind extends string = string,
+  TConfig = Record<string, unknown>,
+> {
+  id: string;
+  kind: TKind;
+  title: string;
+  config: TConfig;
+  ownerEmail: string;
+  orgId: string | null;
+  visibility: "private" | "org" | "public";
+  createdAt: string;
+  updatedAt: string;
+  updatedBy: string | null;
+  archivedAt: string | null;
+}
+
+export interface DashboardRevisionRecord<
+  TKind extends string = string,
+  TConfig = Record<string, unknown>,
+> {
+  id: string;
+  dashboardId: string;
+  kind: TKind;
+  title: string;
+  config: TConfig;
+  createdAt: string;
+  createdBy: string | null;
+}
+
+export interface DashboardWriteInput<
+  TKind extends string = string,
+  TConfig = Record<string, unknown>,
+> {
+  id: string;
+  kind: TKind;
+  title: string;
+  config: TConfig;
+  expectedUpdatedAt?: string;
+}
+
+export class DashboardStorageConflictError extends Error {
+  constructor(id: string) {
+    super(`Dashboard "${id}" changed between read and write.`);
+    this.name = "DashboardStorageConflictError";
+  }
+}
+
+export interface DashboardStorageOptions<TKind extends string, TConfig> {
+  schema: DashboardStorageSchema;
+  getDb: () => any;
+  resourceType: string;
+  displayName?: string;
+  maxRevisions?: number;
+  validateKind?: (kind: string) => kind is TKind;
+  parseConfig?: (raw: string) => TConfig;
+  serializeConfig?: (config: TConfig) => string;
+  getResourcePath?: (dashboard: { id: string }) => string;
+  allowPublic?: boolean;
+  requireOrgMemberForUserShares?: boolean;
+  onChange?: (event: {
+    type: "change" | "delete";
+    dashboard: DashboardRecord<TKind, TConfig>;
+  }) => void;
+}
+
+function affectedRowCount(result: unknown): number | undefined {
+  if (!result || typeof result !== "object") return undefined;
+  const candidate = result as Record<string, unknown>;
+  for (const key of ["rowCount", "rowsAffected", "changes"]) {
+    const value = candidate[key];
+    if (typeof value === "number") return value;
+  }
+  return undefined;
+}
+
+function requireWriter(ctx: AccessContext): string {
+  const email = ctx.userEmail?.trim().toLowerCase();
+  if (!email)
+    throw new Error("Dashboard writes require an authenticated user.");
+  return email;
+}
+
+export function createDashboardStorage<
+  TKind extends string = string,
+  TConfig = Record<string, unknown>,
+>(options: DashboardStorageOptions<TKind, TConfig>) {
+  const parseConfig =
+    options.parseConfig ?? ((raw: string) => JSON.parse(raw) as TConfig);
+  const serializeConfig = options.serializeConfig ?? JSON.stringify;
+  const maxRevisions = Math.max(1, options.maxRevisions ?? 50);
+  const { dashboards, dashboardRevisions, dashboardShares } = options.schema;
+
+  function recordFromRow(row: any): DashboardRecord<TKind, TConfig> {
+    if (options.validateKind && !options.validateKind(row.kind)) {
+      throw new Error(`Unsupported dashboard kind: ${String(row.kind)}`);
+    }
+    return {
+      id: row.id,
+      kind: row.kind as TKind,
+      title: row.title,
+      config: parseConfig(row.config),
+      ownerEmail: row.ownerEmail,
+      orgId: row.orgId ?? null,
+      visibility: row.visibility,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+      updatedBy: row.updatedBy ?? null,
+      archivedAt: row.archivedAt ?? null,
+    };
+  }
+
+  function revisionFromRow(row: any): DashboardRevisionRecord<TKind, TConfig> {
+    return {
+      id: row.id,
+      dashboardId: row.dashboardId,
+      kind: row.kind as TKind,
+      title: row.title,
+      config: parseConfig(row.config),
+      createdAt: row.createdAt,
+      createdBy: row.createdBy ?? null,
+    };
+  }
+
+  async function get(id: string, ctx: AccessContext) {
+    const [row] = await options
+      .getDb()
+      .select()
+      .from(dashboards)
+      .where(
+        and(
+          eq(dashboards.id, id),
+          accessFilter(dashboards, dashboardShares, ctx),
+        ),
+      )
+      .limit(1);
+    return row ? recordFromRow(row) : null;
+  }
+
+  async function list(
+    ctx: AccessContext,
+    archive: "active" | "archived" | "all" = "active",
+  ) {
+    const archiveClause =
+      archive === "active"
+        ? isNull(dashboards.archivedAt)
+        : archive === "archived"
+          ? and(
+              accessFilter(dashboards, dashboardShares, ctx),
+              isNotNull(dashboards.archivedAt),
+            )
+          : undefined;
+    const scope = accessFilter(dashboards, dashboardShares, ctx);
+    const where = archiveClause
+      ? archive === "archived"
+        ? archiveClause
+        : and(scope, archiveClause)
+      : scope;
+    const rows = await options
+      .getDb()
+      .select()
+      .from(dashboards)
+      .where(where)
+      .orderBy(desc(dashboards.updatedAt));
+    return rows.map(recordFromRow);
+  }
+
+  async function pruneRevisions(db: any, dashboardId: string) {
+    const rows = await db
+      .select({ id: dashboardRevisions.id })
+      .from(dashboardRevisions)
+      .where(eq(dashboardRevisions.dashboardId, dashboardId))
+      .orderBy(desc(dashboardRevisions.createdAt));
+    const staleIds = rows
+      .slice(maxRevisions)
+      .map((row: { id: string }) => row.id);
+    if (staleIds.length > 0) {
+      await db
+        .delete(dashboardRevisions)
+        .where(inArray(dashboardRevisions.id, staleIds));
+    }
+  }
+
+  async function snapshot(
+    db: any,
+    dashboard: DashboardRecord<TKind, TConfig>,
+    writer: string,
+  ) {
+    await db.insert(dashboardRevisions).values({
+      id: `dashboard-revision-${randomUUID()}`,
+      dashboardId: dashboard.id,
+      kind: dashboard.kind,
+      title: dashboard.title,
+      config: serializeConfig(dashboard.config),
+      createdBy: writer,
+      ownerEmail: dashboard.ownerEmail,
+      orgId: dashboard.orgId,
+      visibility: dashboard.visibility,
+    });
+    await pruneRevisions(db, dashboard.id);
+  }
+
+  async function write(
+    input: DashboardWriteInput<TKind, TConfig>,
+    ctx: AccessContext,
+  ) {
+    const writer = requireWriter(ctx);
+    const existing = await get(input.id, ctx);
+    const db = options.getDb();
+    if (!existing) {
+      if (input.expectedUpdatedAt !== undefined) {
+        throw new DashboardStorageConflictError(input.id);
+      }
+      await db.insert(dashboards).values({
+        id: input.id,
+        kind: input.kind,
+        title: input.title,
+        config: serializeConfig(input.config),
+        ownerEmail: writer,
+        orgId: ctx.orgId ?? null,
+        visibility: "private",
+        updatedBy: writer,
+      });
+    } else {
+      await assertAccess(options.resourceType, input.id, "editor", ctx);
+      const values = {
+        kind: input.kind,
+        title: input.title,
+        config: serializeConfig(input.config),
+        updatedAt: new Date().toISOString(),
+        updatedBy: writer,
+      };
+      await db.transaction(async (tx: any) => {
+        if (input.expectedUpdatedAt !== undefined) {
+          const result = await tx
+            .update(dashboards)
+            .set(values)
+            .where(
+              and(
+                eq(dashboards.id, input.id),
+                eq(dashboards.updatedAt, input.expectedUpdatedAt),
+              ),
+            );
+          const affected = affectedRowCount(result);
+          if (affected === undefined) {
+            throw new Error(
+              "Dashboard storage requires affected-row counts for conditional writes.",
+            );
+          }
+          if (affected === 0) throw new DashboardStorageConflictError(input.id);
+        } else {
+          await tx
+            .update(dashboards)
+            .set(values)
+            .where(eq(dashboards.id, input.id));
+        }
+        await snapshot(tx, existing, writer);
+      });
+    }
+    const stored = await get(input.id, ctx);
+    if (!stored) throw new Error(`Dashboard "${input.id}" was not persisted.`);
+    options.onChange?.({ type: "change", dashboard: stored });
+    return stored;
+  }
+
+  async function listRevisions(id: string, ctx: AccessContext) {
+    const dashboard = await get(id, ctx);
+    if (!dashboard) return [];
+    await assertAccess(options.resourceType, id, "viewer", ctx);
+    const rows = await options
+      .getDb()
+      .select()
+      .from(dashboardRevisions)
+      .where(eq(dashboardRevisions.dashboardId, id))
+      .orderBy(desc(dashboardRevisions.createdAt))
+      .limit(maxRevisions);
+    return rows.map(revisionFromRow);
+  }
+
+  async function restore(id: string, revisionId: string, ctx: AccessContext) {
+    const existing = await get(id, ctx);
+    if (!existing) return null;
+    await assertAccess(options.resourceType, id, "editor", ctx);
+    const [row] = await options
+      .getDb()
+      .select()
+      .from(dashboardRevisions)
+      .where(
+        and(
+          eq(dashboardRevisions.id, revisionId),
+          eq(dashboardRevisions.dashboardId, id),
+        ),
+      )
+      .limit(1);
+    if (!row) return null;
+    const revision = revisionFromRow(row);
+    return write(
+      {
+        id,
+        kind: revision.kind,
+        title: revision.title,
+        config: revision.config,
+        expectedUpdatedAt: existing.updatedAt,
+      },
+      ctx,
+    );
+  }
+
+  function registerShareable() {
+    registerShareableResource({
+      type: options.resourceType,
+      resourceTable: dashboards,
+      sharesTable: dashboardShares,
+      displayName: options.displayName ?? "Dashboard",
+      titleColumn: "title",
+      getResourcePath: options.getResourcePath,
+      allowPublic: options.allowPublic,
+      requireOrgMemberForUserShares: options.requireOrgMemberForUserShares,
+      getDb: options.getDb,
+    });
+  }
+
+  return { get, list, write, listRevisions, restore, registerShareable };
+}