@agent-native/core 0.127.3 → 0.128.0

package/corpus/core/src/templates/chat/.oxfmtrc.json

@@ -1,8 +0,0 @@
-{
-  "tabWidth": 2,
-  "useTabs": false,
-  "printWidth": 80,
-  "trailingComma": "all",
-  "proseWrap": "preserve",
-  "sortImports": true
-}

package/corpus/core/src/templates/chat/AGENTS.md

@@ -1,77 +0,0 @@
-# Chat — Agent Guide
-
-Chat is the minimal chat-first agent-native app template. Keep chat as the
-primary surface, add actions for real capabilities, and add screens only when a
-workflow needs durable UI around the conversation.
-
-## Core Rules
-
-- Store large file/blob payloads in configured file/blob storage, not SQL: no
-  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
-  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
-  or `resources`; persist URLs, ids, or handles instead.
-- Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
-- Follow the root framework contract: data in SQL, actions first, application
-  state for navigation/selection, and shared agent chat for AI work.
-- Scale effort to the task. A small, well-specified change is a short read, the
-  edit, and the app's existing checks (`pnpm typecheck`, formatter, existing
-  tests) — not a codebase survey, unrequested tests, or browser automation.
-- Use actions for app operations and keep frontend/API parity.
-- Do not add `/api/*` routes for app data. If you are about to create a file
-  under `server/routes/api/`, or middleware to guard one, stop and write a
-  `defineAction` instead. The only exceptions are uploads, streaming, inbound
-  webhooks, OAuth callbacks, public unauthenticated URLs, and non-JSON
-  responses — not auth, settings, search, or CRUD.
-- Treat the chat as the default UI. When the user asks for a capability, prefer
-  adding or improving the action surface first, then add a page, table, form, or
-  widget only when the user needs to inspect, compare, approve, or share durable
-  objects.
-- If the user wants to plug in their own agent backend, keep the app shell and
-  thread UI intact and adapt the chat through the framework's `AgentChatRuntime`
-  connector helpers instead of forking the transcript/composer UI.
-- Keep the action surface small and orthogonal: every action is a tool in the
-  model's context window, so prefer one CRUD-style `update` (patch of fields)
-  over many per-field actions, reach for an existing generic query / escape
-  hatch (`provider-api-*`, dev `db-query`) before minting a new read action,
-  mark UI-only or programmatic actions `agentTool: false` to hide them from the
-  model (distinct from `toolCallable: false`, which only gates the extension
-  iframe), and delete or hide actions the UI no longer uses. See the `actions`
-  skill.
-- Keep database code provider-agnostic and additive.
-- Use `view-screen` or application state when the active page/selection is
-  unclear.
-- For new features, update UI, actions, skills/instructions, and application
-  state when applicable.
-
-## Application State
-
-- `navigation` should describe the current view and selected entity ids. The
-  default chat view is `chat` at `/`.
-- `navigate` may be used to move the UI when the app supports it.
-- `view-screen` is the first tool to call when the user's visible context
-  matters.
-
-## Framework Docs Lookup
-
-- Before implementing or explaining non-trivial Agent Native behavior, use the
-  `agent-native-docs` skill and the built-in `docs-search` action/tool to read
-  the version-matched framework docs bundled with `@agent-native/core`.
-- Use the built-in `source-search` action/tool, or search
-  `node_modules/@agent-native/core/corpus`, when you need current core or
-  first-party template implementation examples.
-- Prefer those installed docs over memory or public docs when package APIs,
-  generated-app conventions, workspaces, actions, or agent surfaces are involved.
-- Before building common workspace or agent UI, read `agent-native-toolkit` to
-  inventory existing public kits and installed package seams.
-- Read `customizing-agent-native` before overriding the chat shell or shared UI.
-  Keep Core thread/runtime behavior and use the supported ladder: configure →
-  compose → eject the smallest presentation unit → propose a shared seam.
-  Preview before `--apply` and commit `agent-native.ejections.json`.
-
-## Skills
-
-Read the relevant root skill before implementation: `adding-a-feature`,
-`actions`, `agent-native-docs`, `agent-native-toolkit`,
-`customizing-agent-native`, `storing-data`,
-`real-time-sync`, `security`, `delegate-to-agent`, `frontend-design`, `shadcn-ui`, and
-`self-modifying-code`.

package/corpus/core/src/templates/chat/CHANGELOG.md

@@ -1,10 +0,0 @@
-# Changelog
-
-All notable user-facing changes to Chat are documented here. Open it any
-time from the command menu (Cmd+K → "What's new").
-
-## 2026-06-23
-
-### Added
-
-- See what's new right inside Chat — a changelog now lives in the command menu (Cmd+K).

package/corpus/core/src/templates/chat/DEVELOPING.md

@@ -1,185 +0,0 @@
-# {{APP_NAME}} — Development Guide
-
-This guide is for development-mode agents editing this app's source code. For app operations and tools, see AGENTS.md.
-
-## Tech Stack
-
-- **Framework:** @agent-native/core + React Router v8 (framework mode)
-- **Frontend:** React 19, Vite, TailwindCSS, shadcn/ui
-- **Routing:** File-based via `flatRoutes()` — SSR shell + client rendering
-- **Backend:** Nitro (via @agent-native/core) — file-based API routing, server plugins, deploy-anywhere presets
-- **State:** SQL-backed (SSE for real-time updates)
-
-## Commands
-
-- **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
-- **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
-- **Start:** `node .output/server/index.mjs` (production)
-
-## Directory Structure
-
-```
-app/                   # React frontend
-  root.tsx             # HTML shell + global providers
-  entry.client.tsx     # Client hydration entry
-  routes.ts            # Route config — flatRoutes()
-  routes/              # File-based page routes (auto-discovered)
-    _index.tsx         # / (chat page)
-  components/          # UI components
-  hooks/               # React hooks
-  lib/                 # Utilities (cn, etc)
-
-server/                # Nitro API server
-  routes/
-    api/               # Route-only endpoints (uploads, webhooks, OAuth, streaming)
-    [...page].get.ts   # SSR catch-all (delegates to React Router)
-  plugins/             # Server plugins (startup logic)
-  lib/                 # Shared server modules
-
-shared/                # Isomorphic code (imported by both client & server)
-
-actions/               # Shared app operations (defineAction; UI uses action hooks)
-  run.ts               # Script dispatcher
-  *.ts                 # Individual actions (pnpm action <name>)
-
-data/                  # Local development database fallback
-
-react-router.config.ts # React Router framework config
-.agents/skills/        # Agent skills — detailed guidance for each rule
-```
-
-## Framework Basics
-
-**SSR-first framework, CSR-by-default content:** This app uses React Router v8 framework mode with `ssr: true`. But virtually every route renders only an SSR shell (loading spinner + meta tags). Normal app data fetching happens on the client via action hooks. Server-side data fetching is the exception — only used for public pages that need SEO/OG tags.
-
-## Chat-First Shape
-
-The `/` route is the app's primary chat surface. Keep it on
-`AgentChatSurface` unless you are intentionally replacing the whole chat
-experience. The left sidebar owns the durable thread list through
-`useChatThreads`; app-specific screens can be added alongside it as nav items
-when they become useful.
-
-For a headless app that later needs UI, this template is the intended landing
-zone: bring the existing actions over, keep their names stable, and let the chat
-call them before adding extra screens. For a custom agent backend, keep the app
-shell and swap the chat runtime with an `AgentChatRuntime` connector instead of
-rewriting the composer/transcript UI.
-
-## Adding a Page
-
-Create a file in `app/routes/`. The filename determines the URL path:
-
-```
-app/routes/_index.tsx              → /
-app/routes/settings.tsx            → /settings
-app/routes/inbox.tsx               → /inbox
-app/routes/inbox.$threadId.tsx     → /inbox/:threadId
-app/routes/$id.tsx                 → /:id (dynamic param)
-```
-
-Each route file exports a default component, optional `meta()`, and optional `HydrateFallback()`:
-
-```tsx
-import MyPage from "@/pages/MyPage";
-
-export function meta() {
-  return [{ title: "My Page" }];
-}
-
-export function HydrateFallback() {
-  return (
-    <div className="flex items-center justify-center h-screen">
-      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-foreground" />
-    </div>
-  );
-}
-
-export default function MyPageRoute() {
-  return <MyPage />;
-}
-```
-
-**Do NOT fetch data server-side** in route loaders unless the page genuinely needs SEO/OG content. The standard pattern is: SSR renders the shell, client hydrates, and React reads/writes normal app data through actions with `useActionQuery` / `useActionMutation`.
-
-## Adding App Data
-
-Normal app data starts as an action, not a custom route. Add `actions/<verb>-<resource>.ts` with `defineAction`, mark reads with `http: { method: "GET" }`, and call reads/writes from React with `useActionQuery` / `useActionMutation` from `@agent-native/core/client`. This keeps the UI and agent on one contract and lets mutating actions refresh action-backed queries automatically.
-
-## Adding a Route-Only Endpoint
-
-Use `server/routes/api/` only for protocols that cannot be modeled as JSON actions: multipart uploads, streaming/SSE/WebSocket, webhooks, OAuth callbacks/redirects, public SEO/OG endpoints, or binary/static asset serving. Do not add `/api/*` routes for normal CRUD, data queries, or pass-through wrappers around actions; the action endpoint already exists at `/_agent-native/actions/:name`.
-
-Each route-only endpoint still exports a default `defineEventHandler`, but keep shared app logic in actions or server libraries so agent and UI behavior do not fork.
-
-## Adding a Server Plugin
-
-Startup logic (auth, SSE, etc.) lives in `server/plugins/`. Use `defineNitroPlugin` from core:
-
-```ts
-import { defineNitroPlugin } from "@agent-native/core";
-
-export default defineNitroPlugin(async (nitroApp) => {
-  // Runs once at server startup
-});
-```
-
-## Key Imports from `@agent-native/core`
-
-| Import                                       | Purpose                                                                    |
-| -------------------------------------------- | -------------------------------------------------------------------------- |
-| `defineNitroPlugin`                          | Define a server plugin (re-exported from Nitro)                            |
-| `createDefaultSSEHandler`                    | Create SSE endpoint for DB change events (server)                          |
-| `readAppState`, `writeAppState`              | Read/write application state (from `@agent-native/core/application-state`) |
-| `readSetting`, `writeSetting`                | Read/write settings (from `@agent-native/core/settings`)                   |
-| `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)                                   |
-| `sendToAgentChat`                            | Send messages to agent from UI (client-side)                               |
-| `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
-
-## Adding an Action
-
-Create `actions/<verb>-<resource>.ts` with `defineAction`. Run with `pnpm action <name> --id value`; React callers should use `useActionQuery` for GET actions and `useActionMutation` for mutating actions, not a matching `/api/*` wrapper.
-
-**Sending to agent chat from UI:**
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client";
-sendToAgentChat({
-  message: "Generate something",
-  context: "...",
-  submit: true,
-});
-```
-
-**Sending to agent chat from scripts:**
-
-```ts
-import { agentChat } from "@agent-native/core";
-agentChat.submit("Generate something");
-```
-
-## Database & Environment Variables
-
-Local development defaults to a SQLite file at `data/app.db`. That local file is for development; containers, previews, and serverless deploys can reset their filesystem. For production/cloud deployment, set `DATABASE_URL` to point to a persistent SQL database. Turso is optional, not required; common choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments when available.
-
-Real credential values belong only in local `.env` files, deployment configuration, or registered secrets/settings UI. Never commit, document, log, return, paste, or include real keys, tokens, webhook URLs, signing secrets, or private data in examples; use empty values or obvious placeholders.
-
-When adding app data, define tables with `@agent-native/core/db/schema` helpers and use Drizzle's query builder for reads/writes. Do not import dialect-specific schema helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`, and do not write raw SQL in normal actions or handlers when Drizzle can express the query. Raw SQL belongs in additive migrations, health checks, or carefully scoped maintenance.
-
-| Variable              | Required                        | Description                                                                |
-| --------------------- | ------------------------------- | -------------------------------------------------------------------------- |
-| `DATABASE_URL`        | Production yes, local dev no    | Persistent SQL connection string (local dev default: `file:./data/app.db`) |
-| `DATABASE_AUTH_TOKEN` | Only when the provider needs it | Auth token for providers such as Turso/libSQL                              |
-| `AUTH_DISABLED`       | Optional                        | Set to `true` or `1` to skip login/signup (local dev/preview only)         |
-
-## Extensions (Framework Feature)
-
-The framework provides **Extensions** — mini sandboxed Alpine.js apps that run inside iframes. Extensions let users (or the agent) create interactive widgets, dashboards, and utilities without modifying the app's source code. They appear in the sidebar under an "Extensions" section. (Distinct from LLM tools — the function-calling primitives the agent invokes.)
-
-- **Creating extensions**: Via the sidebar "+" button, agent chat, or `POST /_agent-native/extensions`
-- **API calls**: Extensions use `extensionFetch()` (legacy alias `toolFetch`) which proxies requests through the server with `${keys.NAME}` secret injection
-- **Styling**: Extensions inherit the main app's Tailwind v4 theme automatically
-- **Sharing**: Private by default, shareable with org or specific users (same model as other ownable resources)
-- **Security**: Iframe sandbox + CSP + SSRF protection on the proxy
-
-See the `extensions` skill in `.agents/skills/extensions/SKILL.md` for full implementation details.

package/corpus/core/src/templates/chat/README.md

@@ -1,32 +0,0 @@
-# Chat
-
-The minimal agent-native starter app — a clean, ChatGPT-style shell with chat at
-the center, durable threads, standard app navigation, auth, live sync, and
-actions. Start here when you want a real browser app to build on without
-committing to a domain template.
-
-**Live app: [chat.agent-native.com](https://chat.agent-native.com)**
-
-Chat is the basic agent-native app starting point. It gives you the app-agent
-loop wired end to end and one example action, so you can add your own UI, data,
-and actions on top.
-
-## Features
-
-- ChatGPT-style shell with a threads list and durable chat history.
-- Auth, live sync, and application state wired out of the box.
-- The action surface the agent and UI share, plus one example action to copy.
-- A minimal, brandable base for any domain app.
-
-## Develop locally
-
-Scaffold your own copy and run it:
-
-```bash
-npx @agent-native/core@latest create my-app --standalone --template chat
-cd my-app
-pnpm install
-pnpm dev
-```
-
-Full docs: [agent-native.com/docs/template-chat](https://agent-native.com/docs/template-chat).

package/corpus/core/src/templates/chat/_gitignore

@@ -1,46 +0,0 @@
-# React Router generated types
-.react-router/
-.generated/
-
-# Logs
-logs
-*.log
-npm-debug.log*
-pnpm-debug.log*
-
-node_modules
-build/
-dist
-dist-ssr
-.output/
-*.local
-
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
-.idea
-.DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
-
-# Environment
-.env
-.env.*
-!.env.example
-
-# Data
-data/*.db
-data/*.db-shm
-data/*.db-wal
-data/uploads/
-data/settings.json
-data/.sessions.json
-
-# Learnings (personal preferences and memory — use learnings.defaults.md for tracked defaults)
-learnings.md
-
-.vercel/
-.agent-native/

package/corpus/core/src/templates/chat/actions/hello.ts

@@ -1,13 +0,0 @@
-import { defineAction } from "@agent-native/core/action";
-import { z } from "zod";
-
-export default defineAction({
-  description: "Return a friendly greeting.",
-  schema: z.object({
-    name: z.string().default("world").describe("Name to greet"),
-  }),
-  http: { method: "GET" },
-  run: async ({ name }) => {
-    return { message: `Hello, ${name}!` };
-  },
-});

package/corpus/core/src/templates/chat/actions/navigate.ts

@@ -1,41 +0,0 @@
-/**
- * Navigate the UI to a view.
- *
- * Writes a navigate command to application state which the UI reads and auto-deletes.
- *
- * Usage:
- *   pnpm action navigate --view=chat
- *   pnpm action navigate --path=/some/route
- *
- * Options:
- *   --view   View name to navigate to
- *   --path   URL path to navigate to
- *   --threadId Chat thread ID to open on the chat route
- */
-
-import { defineAction } from "@agent-native/core/action";
-import { writeAppState } from "@agent-native/core/application-state";
-import { z } from "zod";
-
-export default defineAction({
-  description:
-    "Navigate the UI to a specific view or path. Writes a navigate command to application state which the UI reads and auto-deletes.",
-  schema: z.object({
-    view: z.string().optional().describe("View name to navigate to"),
-    path: z.string().optional().describe("URL path to navigate to"),
-    threadId: z.string().optional().describe("Chat thread ID to open"),
-  }),
-  http: false,
-  run: async (args) => {
-    if (!args.view && !args.path) {
-      throw new Error("At least --view or --path is required.");
-    }
-    const nav: Record<string, string> = {};
-    if (args.view) nav.view = args.view;
-    if (args.path) nav.path = args.path;
-    if (args.threadId) nav.threadId = args.threadId;
-    nav._writeId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    await writeAppState("navigate", nav);
-    return `Navigating to ${args.view || args.path}`;
-  },
-});

package/corpus/core/src/templates/chat/actions/run.ts

@@ -1,2 +0,0 @@
-import { runScript } from "@agent-native/core/scripts";
-runScript();

package/corpus/core/src/templates/chat/actions/view-screen.ts

@@ -1,31 +0,0 @@
-/**
- * See what the user is currently looking at on screen.
- *
- * Reads and returns the current navigation state from application state.
- *
- * Usage:
- *   pnpm action view-screen
- */
-
-import { defineAction } from "@agent-native/core/action";
-import { readAppState } from "@agent-native/core/application-state";
-import { z } from "zod";
-
-export default defineAction({
-  description:
-    "See what the user is currently looking at on screen. Returns the current navigation state for the chat-first app. Always call this first before taking any action.",
-  schema: z.object({}),
-  http: false,
-  readOnly: true,
-  run: async () => {
-    const navigation = await readAppState("navigation");
-
-    const screen: Record<string, unknown> = {};
-    if (navigation) screen.navigation = navigation;
-
-    if (Object.keys(screen).length === 0) {
-      return "No application state found. Is the app running?";
-    }
-    return screen;
-  },
-});

package/corpus/core/src/templates/chat/app/components/layout/Header.tsx

@@ -1,60 +0,0 @@
-import { AgentToggleButton } from "@agent-native/core/client/agent-chat";
-import { useT } from "@agent-native/core/client/i18n";
-import {
-  useHeaderTitle,
-  useHeaderActions,
-} from "@agent-native/toolkit/app-shell";
-import { IconMenu2 } from "@tabler/icons-react";
-import { useLocation } from "react-router";
-
-import { APP_TITLE } from "@/lib/app-config";
-
-const pageTitleKeys: Record<string, string> = {
-  "/": "navigation.chat",
-  "/observability": "navigation.observability",
-  "/agent": "settings.agentTitle",
-  "/settings": "navigation.settings",
-};
-
-function resolveTitle(pathname: string, t: (key: string) => string): string {
-  if (pageTitleKeys[pathname]) return t(pageTitleKeys[pathname]);
-  if (pathname.startsWith("/extensions")) return t("navigation.extensions");
-  return APP_TITLE;
-}
-
-interface HeaderProps {
-  onOpenMobileSidebar?: () => void;
-}
-
-export function Header({ onOpenMobileSidebar }: HeaderProps) {
-  const location = useLocation();
-  const t = useT();
-  const title = useHeaderTitle();
-  const actions = useHeaderActions();
-
-  return (
-    <header className="flex h-12 items-center gap-3 border-b border-border bg-background px-4 lg:px-6 shrink-0">
-      {onOpenMobileSidebar && (
-        <button
-          type="button"
-          onClick={onOpenMobileSidebar}
-          aria-label={t("navigation.openNavigation")}
-          className="flex h-9 w-9 cursor-pointer items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-accent md:hidden"
-        >
-          <IconMenu2 className="h-4 w-4" />
-        </button>
-      )}
-      <div className="flex items-center gap-3 flex-1 min-w-0">
-        {title ?? (
-          <h1 className="text-lg font-semibold tracking-tight truncate">
-            {resolveTitle(location.pathname, t)}
-          </h1>
-        )}
-      </div>
-      <div className="flex items-center gap-2 shrink-0">
-        {actions}
-        <AgentToggleButton />
-      </div>
-    </header>
-  );
-}