@agent-native/core 0.6.1 → 0.7.1

package/dist/templates/workspace-core/AGENTS.md

@@ -0,0 +1,62 @@
+# {{APP_TITLE}} — Enterprise Agent Instructions
+
+These instructions apply to **every app** in the {{APP_TITLE}} workspace. The
+framework auto-injects this file into each app's agent system prompt as a
+`<resource name="AGENTS.md" scope="workspace">` block. Individual apps can
+add their own template-specific AGENTS.md on top.
+
+## Company context
+
+Write a short paragraph here describing your company and what you do. The
+agent reads this first so every response can be grounded in the same
+business context without you having to repeat it per app.
+
+## Shared conventions
+
+- **All cross-app state lives in the shared database.** Apps in this
+  workspace share `DATABASE_URL` by default, so a record created by one
+  app can be read by another as long as it respects the `owner_email` and
+  `org_id` scoping conventions.
+- **All API secrets come from the central credential store.** Never
+  hardcode a token. Call `resolveCompanyCredential("KEY")` from
+  `@{{APP_NAME}}/core-module/credentials` — it pulls from env first and
+  falls back to the shared settings table so one rotation updates every
+  app.
+- **UI chrome comes from the workspace core.** Wrap every screen in
+  `<AuthenticatedLayout>` from `@{{APP_NAME}}/core-module/client`. Don't
+  re-implement the brand header, sidebar, or org switcher per app.
+- **Design system.** If the app needs a button, dialog, or form control,
+  import from our internal design system package (if you have one) or
+  from the shared UI re-exports in `@{{APP_NAME}}/core-module/client`.
+
+## Compliance and policy
+
+List any enterprise-wide rules the agent must follow — data handling, PII
+guidelines, approval flows, deployment constraints. The agent will apply
+these to every decision it makes in every app.
+
+Example rules:
+
+- Never expose raw customer email addresses in logs.
+- Any action that modifies data must first be shown to the user with a
+  preview and wait for confirmation.
+- Never make network calls to anything outside `*.{{APP_NAME}}.com` or
+  the approved third-party allowlist.
+
+## How to add a new app
+
+```bash
+cd apps
+pnpm exec agent-native create <app-name>
+```
+
+The new app will automatically inherit:
+
+1. The workspace auth plugin (Better Auth + company SSO)
+2. The agent chat plugin with this AGENTS.md pre-loaded
+3. Every skill in `packages/core-module/skills/`
+4. Every action in `packages/core-module/actions/`
+5. The shared Tailwind preset and React components
+
+The only files the new app needs to own are its own routes/screens and any
+template-specific actions.

package/dist/templates/workspace-core/actions/company-directory.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared action: look up an employee in the company directory.
+ *
+ * Every app in the workspace inherits this action automatically — no
+ * wiring required. From the agent's perspective it behaves exactly like
+ * a template action: the tool shows up in every app's agent, and calling
+ * it from the UI via `useActionQuery("company-directory", { ... })` Just
+ * Works.
+ *
+ * Replace the stub implementation with a real call to your company
+ * directory (SCIM, Okta Users API, internal /people endpoint, etc.).
+ */
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description:
+    "Look up a person in the {{APP_TITLE}} company directory by name or email. Returns role, team, and manager.",
+  schema: z.object({
+    query: z.string().describe("Name, email, or partial match to search for"),
+  }),
+  run: async (args) => {
+    // TODO: replace with a real lookup. This stub just echoes the query
+    // so the agent has a reasonable no-op while you wire up the real
+    // directory integration.
+    return {
+      results: [
+        {
+          query: args.query,
+          name: "(stub) " + args.query,
+          role: "Unknown",
+          team: "Unknown",
+          manager: null,
+        },
+      ],
+    };
+  },
+});

package/dist/templates/workspace-core/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@{{APP_NAME}}/core-module",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/server/index.ts",
+      "default": "./src/server/index.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./credentials": {
+      "types": "./src/credentials.ts",
+      "default": "./src/credentials.ts"
+    },
+    "./tailwind": {
+      "types": "./tailwind.preset.ts",
+      "default": "./tailwind.preset.ts"
+    }
+  },
+  "dependencies": {
+    "@agent-native/core": "^0.6.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.23",
+    "react": "^18.3.1",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1"
+  }
+}

package/dist/templates/workspace-core/skills/company-policies/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: company-policies
+description: {{APP_TITLE}}-wide policies the agent must enforce for every app — data handling, PII, approval flows, compliance rules.
+---
+
+# {{APP_TITLE}} Company Policies
+
+Every app in the workspace shares these policies. Read this skill before
+taking any action that touches customer data, external services, or
+deployed state.
+
+## Data handling
+
+- **PII minimization.** Only load the fields you actually need. Never
+  `SELECT *` on a table that contains customer records.
+- **No raw customer email in logs.** Hash or redact before logging.
+- **Retention.** Deleted records are soft-deleted first and purged by a
+  scheduled job. Do not write actions that hard-delete customer data.
+
+## Third-party calls
+
+- **Allowlist only.** Only call domains on the approved allowlist
+  (documented in the root `README.md`). If an integration needs a new
+  domain, surface a warning and wait for human approval before making
+  the call.
+- **Secrets come from `resolveCompanyCredential`.** Never hardcode.
+  Never check secrets into git. Rotating a key in the central store
+  updates every app on the next request.
+
+## Approval flows
+
+- **Destructive operations need a confirmation preview.** Any action
+  that modifies production data must first return a preview of the
+  change (what will be created / updated / deleted) and wait for
+  explicit user confirmation before executing.
+
+## Apply across apps
+
+This skill is loaded automatically in every workspace app. If an
+individual app needs different behavior, it can add a same-named skill
+under its own `.agents/skills/company-policies/SKILL.md` and that copy
+will win for that app only.

package/dist/templates/workspace-core/src/client/AuthenticatedLayout.tsx

@@ -0,0 +1,37 @@
+/**
+ * Shared authenticated layout for every app in the @{{APP_NAME}} workspace.
+ *
+ * Provides the common chrome (brand header, user menu, agent chat sidebar)
+ * so individual apps only have to render their own content. Replace this
+ * with a real component that pulls in your design system. Every app
+ * imports it the same way:
+ *
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *
+ *   export default function Home() {
+ *     return (
+ *       <AuthenticatedLayout>
+ *         <h1>My app's screen</h1>
+ *       </AuthenticatedLayout>
+ *     );
+ *   }
+ */
+import type { ReactNode } from "react";
+
+export interface AuthenticatedLayoutProps {
+  children: ReactNode;
+}
+
+// Workspace title — replaced at scaffold time by the create-workspace CLI.
+const WORKSPACE_TITLE = "{{APP_TITLE}}";
+
+export function AuthenticatedLayout({ children }: AuthenticatedLayoutProps) {
+  return (
+    <div className="min-h-screen flex flex-col">
+      <header className="border-b px-6 py-3">
+        <strong>{WORKSPACE_TITLE}</strong>
+      </header>
+      <main className="flex-1 p-6">{children}</main>
+    </div>
+  );
+}

package/dist/templates/workspace-core/src/client/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Client-side entry for @{{APP_NAME}}/core-module.
+ *
+ * This is where shared React components, hooks, and providers that EVERY
+ * app in your workspace needs live. Think of it as the "app shell" layer
+ * between the framework's primitives (@agent-native/core/client) and the
+ * individual app's screens:
+ *
+ *   - Authenticated layouts (header / sidebar / footer with brand)
+ *   - Org switchers wired to your company's org plugin
+ *   - Common chrome: loading states, error boundaries, empty states
+ *   - Wrappers around @agent-native/core components that apply your
+ *     enterprise design tokens
+ *
+ * Apps import from here instead of re-implementing or copy-pasting:
+ *
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *
+ * NOTE: This package does not ship shadcn/ui or a generic design system
+ * by default. If you already have an internal `@{{APP_NAME}}/design-system`
+ * package, add it as a dep here and re-export from this file. Otherwise
+ * you can drop any shadcn components the apps share into `./ui/` and
+ * export them from this index.
+ */
+
+export { AuthenticatedLayout } from "./AuthenticatedLayout.js";

package/dist/templates/workspace-core/src/credentials.ts

@@ -0,0 +1,29 @@
+/**
+ * Centralized credential helpers for the @{{APP_NAME}} workspace.
+ *
+ * Every enterprise has a few API keys that multiple apps need to share:
+ * a Slack bot token, a Sentry DSN, an OpenAI key, internal service
+ * credentials. Instead of each app reading them separately, we namespace
+ * them here so there's a single place to update when a key rotates.
+ *
+ * Under the hood this is a thin wrapper over @agent-native/core's
+ * `resolveCredential()`, which reads `process.env.<KEY>` first and
+ * falls back to `credential:<KEY>` in the shared settings table.
+ * Apps inside the workspace share the same DATABASE_URL by default,
+ * so storing a credential once makes it available everywhere.
+ */
+import { resolveCredential } from "@agent-native/core/credentials";
+
+/**
+ * Resolve a company-wide credential. Prefer this over `resolveCredential()`
+ * directly — it keeps your keys organized under a workspace namespace and
+ * makes "where does this secret come from" greppable.
+ *
+ * Example:
+ *   const slackToken = await resolveCompanyCredential("SLACK_BOT_TOKEN");
+ */
+export async function resolveCompanyCredential(
+  key: string,
+): Promise<string | undefined> {
+  return await resolveCredential(key);
+}

package/dist/templates/workspace-core/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @{{APP_NAME}}/core-module — enterprise-wide workspace core.
+ *
+ * Every agent-native app in this workspace inherits from this package:
+ *   - Server plugins (auth, org, agent-chat) — see src/server
+ *   - Shared React components and hooks — see src/client
+ *   - Shared agent actions — see actions/
+ *   - Shared agent skills — see skills/
+ *   - Enterprise-wide agent instructions — see AGENTS.md
+ *   - Shared Tailwind preset — see tailwind.preset.ts
+ *
+ * Apps don't import from this root entry directly — they import from
+ * the specific sub-path they need:
+ *
+ *   import { authPlugin } from "@{{APP_NAME}}/core-module/server";
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *   import { resolveCompanyCredential } from "@{{APP_NAME}}/core-module/credentials";
+ *
+ * This root file is for package metadata only.
+ */
+export const WORKSPACE_CORE_NAME = "@{{APP_NAME}}/core-module";

package/dist/templates/workspace-core/src/server/agent-chat-plugin.ts

@@ -0,0 +1,30 @@
+/**
+ * Workspace-wide agent-chat plugin for @{{APP_NAME}}/core-module.
+ *
+ * This mounts the framework's default agent-chat plugin so every app in
+ * the workspace gets the same chat endpoint, mention providers, and
+ * built-in tools. The ENTERPRISE-WIDE system prompt additions — things
+ * the agent should know across every app — live in the workspace's
+ * AGENTS.md file, which is loaded automatically into the prompt as a
+ * `<resource scope="workspace">` block.
+ *
+ * Customize this wrapper when you need agent behavior that can't be
+ * expressed in AGENTS.md — e.g. injecting enterprise-specific mention
+ * providers, pre-loading a custom set of MCP servers, or rewriting
+ * model choice based on your company's allowlist.
+ */
+import { defaultAgentChatPlugin } from "@agent-native/core/server";
+
+export const agentChatPlugin = async (nitroApp: any): Promise<void> => {
+  await defaultAgentChatPlugin(nitroApp);
+
+  // Hook for enterprise customization:
+  //
+  //   const chat = createAgentChatPlugin({
+  //     systemPrompt: (base) => `${base}\n\nCompany policy: …`,
+  //     mentionProviders: {
+  //       people: async (query) => searchCompanyDirectory(query),
+  //     },
+  //   });
+  //   await chat(nitroApp);
+};

package/dist/templates/workspace-core/src/server/auth-plugin.ts

@@ -0,0 +1,35 @@
+/**
+ * Workspace-wide auth plugin for @{{APP_NAME}}/core-module.
+ *
+ * Today this just re-uses the framework default, which already does the
+ * right thing for most enterprises (Better Auth with Google SSO when
+ * GOOGLE_CLIENT_ID/SECRET are set, email/password otherwise, local dev
+ * bypass via AUTH_MODE=local). Customize it here when your enterprise
+ * needs specific behavior — e.g.:
+ *
+ *   - Wrap the default to force a specific SSO provider
+ *   - Add a callback that provisions users into your directory
+ *   - Pre-register organizations / role mappings from Okta groups
+ *   - Fail closed on unauthenticated requests outside dev
+ *
+ * Every app in the workspace inherits this automatically (as long as the
+ * root package.json has `"agent-native": { "workspaceCore": "@{{APP_NAME}}/core-module" }`).
+ */
+import { defaultAuthPlugin } from "@agent-native/core/server";
+
+export const authPlugin = async (nitroApp: any): Promise<void> => {
+  // Run the framework default first so Better Auth, org tables, and session
+  // middleware are all set up.
+  await defaultAuthPlugin(nitroApp);
+
+  // Add enterprise-specific post-auth behavior here. Examples:
+  //
+  //   const h3 = getH3App(nitroApp);
+  //   h3.use(defineEventHandler(async (event) => {
+  //     const session = await getSession(event);
+  //     if (session?.email && !session.email.endsWith("@{{APP_NAME}}.com")) {
+  //       setResponseStatus(event, 403);
+  //       return { error: "Only @{{APP_NAME}}.com accounts allowed" };
+  //     }
+  //   }));
+};

package/dist/templates/workspace-core/src/server/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Server-side entry for @{{APP_NAME}}/core-module.
+ *
+ * Exports plugin overrides for any framework slot you want to customize
+ * across every app in this workspace. The agent-native framework looks for
+ * these exports by name when deciding what to auto-mount — see the "three
+ * layer inheritance" section in the root README.
+ *
+ * Supported export names (any subset):
+ *   - authPlugin            → overrides @agent-native/core's auth
+ *   - orgPlugin             → overrides @agent-native/core's org
+ *   - agentChatPlugin       → overrides @agent-native/core's agent-chat
+ *   - coreRoutesPlugin      → overrides @agent-native/core's core-routes
+ *   - integrationsPlugin    → overrides @agent-native/core's integrations
+ *   - resourcesPlugin       → overrides @agent-native/core's resources
+ *   - terminalPlugin        → overrides @agent-native/core's terminal
+ *
+ * Anything you don't export falls through to the framework default.
+ */
+
+export { authPlugin } from "./auth-plugin.js";
+export { agentChatPlugin } from "./agent-chat-plugin.js";

package/dist/templates/workspace-core/tailwind.preset.ts

@@ -0,0 +1,34 @@
+/**
+ * Workspace-wide Tailwind preset for @{{APP_NAME}}/core-module.
+ *
+ * Extends the framework's base preset with enterprise brand tokens. Every
+ * app in the workspace should import THIS preset in its own
+ * tailwind.config.ts instead of importing @agent-native/core/tailwind
+ * directly, so brand updates in one place propagate to all apps.
+ *
+ *   // apps/<name>/tailwind.config.ts
+ *   import preset from "@{{APP_NAME}}/core-module/tailwind";
+ *   export default { presets: [preset], content: ["./app/**\/*.{ts,tsx}"] };
+ *
+ * If your enterprise already has a design-system package with its own
+ * Tailwind preset, swap `corePreset` out for that one (or chain both).
+ */
+import corePreset from "@agent-native/core/tailwind";
+import type { Config } from "tailwindcss";
+
+const preset: Partial<Config> = {
+  presets: [corePreset],
+  theme: {
+    extend: {
+      colors: {
+        // Replace with your actual brand palette.
+        brand: {
+          DEFAULT: "#4f46e5",
+          foreground: "#ffffff",
+        },
+      },
+    },
+  },
+};
+
+export default preset;

package/dist/templates/workspace-core/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmit": true
+  },
+  "include": ["src/**/*", "tailwind.preset.ts"]
+}

package/dist/templates/workspace-root/.env.example

@@ -0,0 +1,37 @@
+# Shared across every app in this workspace.
+# Copy to .env and fill in values, or override per-app in apps/<app>/.env.
+# Per-app values win on conflict — use workspace-level for shared secrets.
+
+# Database shared by every app in the workspace. Leave blank to default to
+# SQLite per app (apps/<app>/data/app.db), or set DATABASE_URL per app.
+DATABASE_URL=
+
+# Better Auth — required for login to work. Generate with:
+#   openssl rand -hex 32
+BETTER_AUTH_SECRET=
+
+# Anthropic API key for the agent chat.
+ANTHROPIC_API_KEY=
+
+# Optional: OpenAI key if any app uses OpenAI engines.
+OPENAI_API_KEY=
+
+# Builder browser integration (run `agent-native dev` and visit any app,
+# then click "Connect Builder" — these are written automatically by the
+# callback handler to this workspace-level .env).
+BUILDER_PRIVATE_KEY=
+BUILDER_PUBLIC_KEY=
+
+# A2A shared secret — required for cross-app JWT verification. Every app
+# in the workspace should use the same value. Generate with:
+#   openssl rand -hex 32
+A2A_SECRET=
+
+# Google sign-in — optional. Leave blank to use email/password only.
+# Both values come from Google Cloud Console → APIs & Services → Credentials.
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+# Optional: GitHub sign-in.
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=

package/dist/templates/workspace-root/README.md

@@ -0,0 +1,62 @@
+# {{APP_TITLE}} — Agent-Native Workspace
+
+A monorepo hosting multiple agent-native apps that all inherit from a single
+private **workspace core** package. The core module provides shared auth,
+agent instructions, skills, components, and plugins; each app just ships its
+own screens and template-specific actions.
+
+## Layout
+
+```
+{{APP_NAME}}/
+├── packages/
+│   └── core-module/          # @{{APP_NAME}}/core-module — the shared mid-layer
+│       ├── src/server/       # Auth / org / agent-chat plugin overrides
+│       ├── src/client/       # Shared React components (org switcher, layouts…)
+│       ├── actions/          # Shared agent-callable actions
+│       ├── skills/           # Shared .agents skills baked into every app
+│       └── AGENTS.md         # Enterprise-wide agent instructions
+└── apps/
+    └── example/              # Sample app demonstrating inheritance
+```
+
+## Three-layer inheritance
+
+Every app in this workspace inherits cross-cutting behavior automatically:
+
+1. **App local** (highest priority) — anything under `apps/<name>/server/plugins/`,
+   `apps/<name>/actions/`, `apps/<name>/.agents/skills/`, `apps/<name>/AGENTS.md`.
+2. **Workspace core** (middle) — `packages/core-module/src/server/`,
+   `packages/core-module/actions/`, `packages/core-module/skills/`,
+   `packages/core-module/AGENTS.md`.
+3. **Framework** (lowest) — `@agent-native/core` defaults.
+
+Apps don't need any configuration to opt in. Discovery happens via the
+`agent-native.workspaceCore` field in this root `package.json`, which names
+the workspace core package (`@{{APP_NAME}}/core-module`).
+
+## Getting started
+
+```bash
+pnpm install
+cp .env.example .env   # fill in DATABASE_URL, BETTER_AUTH_SECRET, ANTHROPIC_API_KEY
+pnpm dev               # starts the example app
+```
+
+## Adding a new app
+
+```bash
+cd apps
+pnpm exec agent-native create crm
+```
+
+The CLI detects the workspace root and scaffolds a minimal app that already
+depends on `@{{APP_NAME}}/core-module`. Edit only the routes you care about;
+auth, org switching, skills, and instructions come from the core module.
+
+## Editing shared behavior
+
+Everything cross-cutting lives in `packages/core-module/`. A change to
+`packages/core-module/src/server/auth-plugin.ts`, for example, is picked up
+by every app in the workspace on the next dev reload — no need to touch any
+individual app.

package/dist/templates/workspace-root/_gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+build/
+.deploy-tmp/
+
+# Env files — never commit secrets
+.env
+.env.local
+apps/*/.env
+apps/*/.env.local
+packages/*/.env
+
+# Editor / OS
+.DS_Store
+.vscode/
+.idea/
+
+# pnpm
+.pnpm-store/
+pnpm-debug.log*
+
+# Personal agent memory — per-developer, not shared
+learnings.md

package/dist/templates/workspace-root/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{APP_NAME}}",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "dev": "pnpm --filter example dev",
+    "build": "pnpm -r build",
+    "typecheck": "pnpm -r typecheck"
+  },
+  "agent-native": {
+    "workspaceCore": "@{{APP_NAME}}/core-module"
+  },
+  "devDependencies": {
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2"
+  },
+  "packageManager": "pnpm@10.14.0"
+}

package/dist/templates/workspace-root/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+packages:
+  - "packages/*"
+  - "apps/*"

package/dist/templates/workspace-root/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package/dist/vite/agents-bundle-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-bundle-plugin.d.ts","sourceRoot":"","sources":["../../src/vite/agents-bundle-plugin.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAkBnC,wBAAgB,kBAAkB,IAAI,MAAM,CA2D3C"}
+{"version":3,"file":"agents-bundle-plugin.d.ts","sourceRoot":"","sources":["../../src/vite/agents-bundle-plugin.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAwCnC,wBAAgB,kBAAkB,IAAI,MAAM,CA6F3C"}