@agent-native/core 0.6.1 → 0.7.1

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/templates/workspace-root/pnpm-workspace.yaml

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

package/src/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/templates/templates/default/.agents/skills/actions/SKILL.md

@@ -1,142 +0,0 @@
----
-name: actions
-description: >-
-  How to create and run agent-callable actions in actions/. Use when creating
-  a new action, adding an API integration, implementing a complex agent
-  operation, or running pnpm action commands.
----
-
-# Agent Actions
-
-## Rule
-
-Complex operations the agent needs to perform are implemented as actions in `actions/`. The agent runs them via `pnpm action <name>`.
-
-## Why
-
-Actions give the agent callable tools with structured input/output. They keep the agent's chat context clean (no massive code blocks), they're reusable, and they can be tested independently.
-
-## How to Create an Action
-
-Create `actions/my-action.ts`:
-
-```ts
-import fs from "fs";
-import { parseArgs, loadEnv, fail, agentChat } from "@agent-native/core";
-
-export default async function myAction(args: string[]) {
-  loadEnv();
-
-  const parsed = parseArgs(args);
-  const input = parsed.input;
-  if (!input) fail("--input is required");
-
-  const outputPath = parsed.output ?? "data/result.json";
-  const raw = fs.readFileSync(input, "utf-8");
-  const data = JSON.parse(raw) as unknown;
-
-  fs.writeFileSync(outputPath, JSON.stringify(data, null, 2));
-  agentChat.submit(`Processed ${input}, result saved to ${outputPath}`);
-}
-```
-
-### Using `defineAction` with Zod schema (recommended for new actions)
-
-```ts
-import { z } from "zod";
-import { defineAction } from "@agent-native/core";
-
-export default defineAction({
-  description: "Process some data",
-  schema: z.object({
-    input: z.string().describe("Input file path"),
-    output: z.string().optional().describe("Output file path"),
-  }),
-  run: async (args) => {
-    // args is fully typed: { input: string; output?: string }
-    // do work
-    return "Done";
-  },
-});
-```
-
-The `schema` field accepts a Zod schema (or any Standard Schema-compatible library). It provides runtime validation with clear error messages, TypeScript type inference for `run()` args, and auto-generated JSON Schema for the agent's tool definition. `zod` is a dependency of all templates.
-
-The legacy `parameters` field (plain JSON Schema object) still works as a fallback.
-
-## How to Run
-
-```bash
-pnpm action my-action --input data/source.json --output data/result.json
-```
-
-## Action Dispatcher
-
-The default template uses core's `runScript()` in `actions/run.ts`:
-
-```ts
-import { runScript } from "@agent-native/core";
-runScript();
-```
-
-This is the canonical approach for new apps. Action names must be lowercase with hyphens only (e.g., `my-action`).
-
-## Guidelines
-
-- **One action, one job.** Keep actions focused on a single operation. The agent composes multiple action calls for complex operations.
-- **Use `parseArgs()`** for structured argument parsing. It converts `--key value` pairs to a `Record<string, string>`.
-- **Use `loadEnv()`** if the action needs environment variables (API keys, etc.).
-- **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
-- **Write results to the database.** The agent and UI will pick them up via db sync polling.
-- **Use `agentChat.submit()`** to report results or errors back to the agent chat.
-- **Import from `@agent-native/core`** -- Don't redefine `parseArgs()` or other utilities locally.
-
-## Common Patterns
-
-**API integration action** (e.g., image generation):
-
-```ts
-import fs from "fs";
-import { parseArgs, loadEnv, fail } from "@agent-native/core";
-
-export default async function generateImage(args: string[]) {
-  loadEnv();
-  const parsed = parseArgs(args);
-  const prompt = parsed.prompt;
-  if (!prompt) fail("--prompt is required");
-
-  const outputPath = parsed.output ?? "data/generated-image.png";
-  const imageUrl = await callImageAPI(prompt);
-  const buffer = await fetch(imageUrl).then((r) => r.arrayBuffer());
-  fs.writeFileSync(outputPath, Buffer.from(buffer));
-}
-```
-
-**Data processing action:**
-
-```ts
-import fs from "fs";
-import { parseArgs, fail } from "@agent-native/core";
-
-export default async function transform(args: string[]) {
-  const parsed = parseArgs(args);
-  const source = parsed.source;
-  if (!source) fail("--source is required");
-
-  const data = JSON.parse(fs.readFileSync(source, "utf-8")) as unknown[];
-  const result = data.map(transformItem);
-  fs.writeFileSync(source, JSON.stringify(result, null, 2));
-}
-```
-
-## Troubleshooting
-
-- **Action not found** -- Check that the filename matches the command name exactly. `pnpm action foo-bar` looks for `actions/foo-bar.ts`.
-- **Args not parsing** -- Ensure args use `--key value` or `--key=value` format. Boolean flags use `--flag` (sets value to `"true"`).
-- **Action runs but UI doesn't update** -- Make sure results are written to the database so db sync polling picks them up.
-
-## Related Skills
-
-- **storing-data** -- Actions read/write data via SQL
-- **delegate-to-agent** -- The agent invokes actions via `pnpm action <name>`
-- **real-time-sync** -- Database writes from actions trigger poll events to update the UI

package/dist/templates/templates/default/.agents/skills/agent-engines/SKILL.md

@@ -1,127 +0,0 @@
----
-name: agent-engines
-description: >-
-  How to inspect and configure the AI engine (model provider) powering the
-  agent. Use when the user asks to switch models, check which engine is active,
-  test a new provider, or register a custom engine.
----
-
-# Agent Engines
-
-## Overview
-
-The framework supports pluggable AI engines beneath the agent loop. The **Anthropic engine** is the default and best-in-class path (Claude models). Additional engines can be added via the Vercel AI SDK (OpenAI, Google Gemini, Groq, Mistral, Cohere, Ollama).
-
-## Available Tools
-
-| Tool | Purpose |
-|---|---|
-| `list-agent-engines` | List all registered engines, their capabilities, and the current selection |
-| `set-agent-engine` | Set the active engine and model (persisted in settings) |
-| `test-agent-engine` | Send a trivial prompt to verify the engine works (connectivity + API key) |
-
-## Checking the Current Engine
-
-```
-list-agent-engines
-```
-
-Returns the registry of all engines (name, label, capabilities, supported models) plus the currently active engine and model.
-
-## Switching Engines
-
-```
-set-agent-engine --engine "ai-sdk:openai" --model "gpt-4o"
-```
-
-Changes take effect on the next conversation. The setting is persisted via the settings store (`agent-engine` key).
-
-Resolution order (highest priority first):
-1. Explicit `engine` option passed to `createAgentChatPlugin()` in the server plugin
-2. Settings store (`agent-engine` key)
-3. `AGENT_ENGINE` environment variable
-4. Default: `"anthropic"` (requires `ANTHROPIC_API_KEY`)
-
-## Testing a New Engine
-
-Before switching, verify the engine is working:
-
-```
-test-agent-engine --engine "ai-sdk:openai" --model "gpt-4o"
-```
-
-Returns `{ ok, latencyMs, response, capabilities }`. If `ok: false`, the error message explains what's wrong (missing API key, package not installed, etc.).
-
-## Built-in Engines
-
-| Engine Name | Provider | Requires |
-|---|---|---|
-| `anthropic` | Anthropic Claude SDK | `ANTHROPIC_API_KEY` |
-| `ai-sdk:anthropic` | Claude via Vercel AI SDK | `ANTHROPIC_API_KEY` |
-| `ai-sdk:openai` | OpenAI via Vercel AI SDK | `OPENAI_API_KEY` |
-| `ai-sdk:google` | Google Gemini via Vercel AI SDK | `GOOGLE_GENERATIVE_AI_API_KEY` |
-| `ai-sdk:groq` | Groq LPU via Vercel AI SDK | `GROQ_API_KEY` |
-| `ai-sdk:mistral` | Mistral via Vercel AI SDK | `MISTRAL_API_KEY` |
-| `ai-sdk:cohere` | Cohere via Vercel AI SDK | `COHERE_API_KEY` |
-| `ai-sdk:ollama` | Local Ollama via Vercel AI SDK | None (local) |
-
-## Engine Capabilities
-
-Each engine advertises its capabilities:
-
-| Capability | Anthropic | AI SDK: Anthropic | AI SDK: OpenAI | AI SDK: Google |
-|---|---|---|---|---|
-| `thinking` | ✓ | ✓ | ✗ | ✓ |
-| `promptCaching` | ✓ | ✓ | ✗ | ✗ |
-| `vision` | ✓ | ✓ | ✓ | ✓ |
-| `computerUse` | ✓ | ✗ | ✗ | ✗ |
-| `parallelToolCalls` | ✓ | ✓ | ✓ | ✓ |
-
-## Anthropic-Exclusive Features
-
-When using the `anthropic` engine (or `ai-sdk:anthropic`):
-
-- **Prompt caching** is applied automatically to the system prompt — cutting latency and cost on repeated turns.
-- **Extended thinking** can be enabled via `providerOptions.anthropic.thinking` — the agent reasons longer before responding.
-
-These features are silently ignored when a non-Anthropic engine is active (capability-gated, no breakage).
-
-## Registering a Custom Engine
-
-Register custom engines in a server plugin at startup:
-
-```ts
-// server/plugins/my-engine.ts
-import { registerAgentEngine } from "@agent-native/core/server";
-
-registerAgentEngine({
-  name: "my-engine",
-  label: "My Custom Engine",
-  description: "...",
-  capabilities: {
-    thinking: false,
-    promptCaching: false,
-    vision: false,
-    computerUse: false,
-    parallelToolCalls: true,
-  },
-  defaultModel: "my-model-v1",
-  supportedModels: ["my-model-v1", "my-model-v2"],
-  requiredEnvVars: ["MY_ENGINE_API_KEY"],
-  create: (config) => new MyEngine(config),
-});
-```
-
-After registering, the engine appears in `list-agent-engines` output and can be selected via `set-agent-engine`.
-
-## Env Vars Reference
-
-| Variable | Purpose |
-|---|---|
-| `ANTHROPIC_API_KEY` | Required for `anthropic` and `ai-sdk:anthropic` engines |
-| `OPENAI_API_KEY` | Required for `ai-sdk:openai` |
-| `GOOGLE_GENERATIVE_AI_API_KEY` | Required for `ai-sdk:google` |
-| `GROQ_API_KEY` | Required for `ai-sdk:groq` |
-| `MISTRAL_API_KEY` | Required for `ai-sdk:mistral` |
-| `COHERE_API_KEY` | Required for `ai-sdk:cohere` |
-| `AGENT_ENGINE` | Default engine name (overridden by settings store) |

package/dist/templates/templates/default/.agents/skills/capture-learnings/SKILL.md

@@ -1,50 +0,0 @@
----
-name: capture-learnings
-description: >-
-  Capture and apply accumulated knowledge in learnings.md. Use when the user
-  corrects a mistake, when debugging reveals unexpected behavior, or when an
-  architectural decision should be recorded for future reference.
-user-invocable: false
----
-
-# Capture Learnings
-
-This is background knowledge, not a slash command. Read `learnings.md` before starting significant work. Update it when you discover something worth remembering.
-
-## When to Capture
-
-Use judgment, not rules. Capture when:
-
-- **Surprising behavior** — Something didn't work as expected and you figured out why
-- **Repeated friction** — You hit the same issue twice; write it down so there's no third time
-- **Architectural decisions** — Why something is done a certain way (the "why" isn't in the code)
-- **API/library quirks** — Undocumented behavior, version-specific gotchas
-- **Performance insights** — What's slow and what fixed it
-
-Don't capture:
-
-- Things that are obvious from reading the code
-- Standard language/framework behavior
-- Temporary debugging notes
-
-## Format
-
-Add entries to `learnings.md` at the project root. Match the existing format — typically a heading per topic with a brief explanation:
-
-```markdown
-## [Topic]
-
-[What you learned and why it matters. Keep it to 2-3 sentences.]
-```
-
-## Graduation
-
-When a learning is referenced repeatedly, it's outgrowing `learnings.md`. Propose adding it to the relevant skill or creating a new skill via `create-skill`.
-
-- Updating `learnings.md` is a Tier 1 modification (data — auto-apply)
-- Updating a SKILL.md based on learnings is Tier 2 (source — verify after)
-
-## Related Skills
-
-- **self-modifying-code** — Learnings.md updates are Tier 1; skill updates are Tier 2
-- **create-skill** — When a learning graduates, create a skill from it