@agent-native/core 0.114.16 → 0.115.1

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

@@ -0,0 +1,254 @@
+export const CRM_PROVIDERS = [
+  "hubspot",
+  "salesforce",
+  "native",
+  "custom",
+] as const;
+
+export type CrmProvider = (typeof CRM_PROVIDERS)[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;
+}
+
+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-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"]
+}

package/corpus/templates/crm/vite.config.ts

@@ -0,0 +1,15 @@
+import { agentNative } from "@agent-native/core/vite";
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+const reactRouterPlugins = reactRouter as unknown as () => any[];
+const agentNativePlugins = agentNative as unknown as (
+  options?: Parameters<typeof agentNative>[0],
+) => any[];
+
+export default defineConfig({
+  plugins: [
+    ...reactRouterPlugins(),
+    ...agentNativePlugins({ ssrStubs: ["shiki"] }),
+  ],
+});

package/corpus/templates/crm/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { include: ["**/*.test.ts"], environment: "node" },
+});

package/corpus/templates/design/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs and source bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
+  features.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`. When examples,
+imports, or implementation details matter, inspect the packaged source corpus
+too.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you. It also includes a source-only corpus of core and
+first-party templates so agents can replicate current best-practice patterns
+without needing the framework monorepo checkout.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+pnpm action source-search --query "<pattern>"
+pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
+pnpm action source-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
+
+If the action runner is unavailable, search the package directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`. For source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
+
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
+
+## Reuse Proven Patterns (rg + cp)
+
+Version-matched installed source outranks web docs or memory: it is the exact
+code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
+holds source for every first-party template, not just the one this app started
+from, so a pattern from the mail template is fair game for a tasks app. Grep
+across it, then copy a whole file as a starting point instead of writing the
+pattern from scratch:
+
+```bash
+# Find how other templates solved a similar problem
+rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
+
+# Grab a proven action file as a starting point, then adapt names/schema
+cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
+   actions/archive-item.ts
+
+# Read the full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+Copying template-level app code (actions, components, skill files) is the
+expected reuse path — templates exist to be forked. This is different from
+copying `core`/`toolkit` **runtime internals**: for those, follow
+`customizing-agent-native`'s configure/compose/eject ladder instead of
+hand-duplicating framework logic.
+
+## Useful Slugs
+
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.
+- Do not copy framework runtime internals when a public API or narrow UI copy
+  will do; read `customizing-agent-native` for the supported override ladder.

package/corpus/templates/dispatch/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs and source bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
+  features.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`. When examples,
+imports, or implementation details matter, inspect the packaged source corpus
+too.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you. It also includes a source-only corpus of core and
+first-party templates so agents can replicate current best-practice patterns
+without needing the framework monorepo checkout.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+pnpm action source-search --query "<pattern>"
+pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
+pnpm action source-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
+
+If the action runner is unavailable, search the package directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`. For source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
+
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
+
+## Reuse Proven Patterns (rg + cp)
+
+Version-matched installed source outranks web docs or memory: it is the exact
+code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
+holds source for every first-party template, not just the one this app started
+from, so a pattern from the mail template is fair game for a tasks app. Grep
+across it, then copy a whole file as a starting point instead of writing the
+pattern from scratch:
+
+```bash
+# Find how other templates solved a similar problem
+rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
+
+# Grab a proven action file as a starting point, then adapt names/schema
+cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
+   actions/archive-item.ts
+
+# Read the full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+Copying template-level app code (actions, components, skill files) is the
+expected reuse path — templates exist to be forked. This is different from
+copying `core`/`toolkit` **runtime internals**: for those, follow
+`customizing-agent-native`'s configure/compose/eject ladder instead of
+hand-duplicating framework logic.
+
+## Useful Slugs
+
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.
+- Do not copy framework runtime internals when a public API or narrow UI copy
+  will do; read `customizing-agent-native` for the supported override ladder.