@agent-native/core 0.135.1 → 0.135.2

package/docs/content/getting-started-database.mdx

@@ -0,0 +1,253 @@
+---
+title: "Persist Data in SQL"
+description: "Save action results to a SQL database so the agent can reference them across conversations."
+---
+
+# Persist Data in SQL
+
+This is part three of the Getting Started series. In [Add an Action](/docs/getting-started-actions) you defined the `analyze-text` action and rendered its result inline in chat. Here you'll persist those results to a SQL database.
+
+## Persist data in SQL {#persist-data}
+
+Right now, every time the agent runs `analyze-text` the result appears in chat
+and then disappears. There's nothing to look back at, nothing the agent can
+reference later, and no way to build a page around the data. Persisting to SQL
+fixes that: the agent writes results to a table, and both the agent and your UI
+can read them back at any time.
+
+Agent-Native apps have a SQL database available by default: SQLite locally,
+and your configured provider (Postgres, Turso/libSQL, Cloudflare D1) in
+production.
+
+### Wire up the database plugin
+
+The Chat template doesn't include a database plugin by default. Create
+`server/plugins/db.ts` to initialize it. This is what runs migrations and
+makes the database available to your actions:
+
+```ts filename="server/plugins/db.ts"
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS text_analyses (
+        id TEXT PRIMARY KEY,
+        input TEXT NOT NULL,
+        char_count INTEGER NOT NULL,
+        word_count INTEGER NOT NULL,
+        sentence_count INTEGER NOT NULL,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      )`,
+    },
+  ],
+  { table: "text_analyses_migrations" },
+);
+```
+
+Each entry in the array is an additive migration. When you add new columns or
+tables later, append a new version object. Never edit existing ones.
+
+### Define the schema
+
+Create `server/db/schema.ts`. The `server/db/` directory may not exist yet,
+so create it if needed. This file describes your tables using typed helpers so
+your actions get full TypeScript autocomplete:
+
+```ts filename="server/db/schema.ts"
+import { integer, now, table, text } from "@agent-native/core/db/schema";
+
+export const textAnalyses = table("text_analyses", {
+  id: text("id").primaryKey(),
+  input: text("input").notNull(),
+  charCount: integer("char_count").notNull(),
+  wordCount: integer("word_count").notNull(),
+  sentenceCount: integer("sentence_count").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+Use the framework schema helpers (`table`, `text`, `integer`, `now`) rather than
+`sqliteTable`, `pgTable`, or dialect-specific imports. They pick the configured
+SQL backend automatically, so the same schema runs locally on SQLite and in
+production on any supported provider.
+
+After adding both files, restart the dev server so the migration runs:
+
+```bash
+pnpm dev
+```
+
+Look for these two lines in the terminal output. They confirm the table was created:
+
+```
+[db] Applying 1 migration(s) on SQLite/libsql…
+[db] Applied migration v1 (1 statement)
+```
+
+The `NitroViteError` lines, `BETTER_AUTH_SECRET` warning, and
+`SECRETS_ENCRYPTION_KEY` warning that also appear are normal for local dev and
+can be ignored.
+
+### Add actions for the table
+
+Now create the action files that read and write the table. These go in your
+`actions/` directory, the same place as `hello.ts` and `analyze-text.ts`. You
+create them yourself, one file per operation. The agent and your UI will call
+them the same way they call any other action.
+
+**`actions/save-text-analysis.ts`** writes a result row to the database.
+Call this after running `analyze-text` to make the result durable:
+
+```ts filename="actions/save-text-analysis.ts"
+import { defineAction } from "@agent-native/core/action";
+import { getDbExec } from "@agent-native/core/db";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Save a text analysis result to the database.",
+  schema: z.object({
+    input: z.string(),
+    charCount: z.number(),
+    wordCount: z.number(),
+    sentenceCount: z.number(),
+  }),
+  run: async ({ input, charCount, wordCount, sentenceCount }) => {
+    const id = crypto.randomUUID();
+    await getDbExec().execute({
+      sql: `INSERT INTO text_analyses (id, input, char_count, word_count, sentence_count)
+            VALUES (?, ?, ?, ?, ?)`,
+      args: [id, input, charCount, wordCount, sentenceCount],
+    });
+    return { id };
+  },
+});
+```
+
+**`actions/list-text-analyses.ts`** reads all saved results. The agent can
+call this to summarize past analyses, and your UI can use it to populate a page:
+
+```ts filename="actions/list-text-analyses.ts"
+import { defineAction } from "@agent-native/core/action";
+import { getDbExec } from "@agent-native/core/db";
+import { z } from "zod";
+
+export default defineAction({
+  description: "List all saved text analyses, newest first.",
+  schema: z.object({}),
+  run: async () => {
+    const result = await getDbExec().execute(
+      `SELECT id, input, char_count, word_count, sentence_count, created_at
+       FROM text_analyses
+       ORDER BY created_at DESC`,
+    );
+    return result.rows;
+  },
+});
+```
+
+**`actions/delete-text-analysis.ts`** removes a row by id:
+
+```ts filename="actions/delete-text-analysis.ts"
+import { defineAction } from "@agent-native/core/action";
+import { getDbExec } from "@agent-native/core/db";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Delete a saved text analysis by id.",
+  schema: z.object({ id: z.string() }),
+  run: async ({ id }) => {
+    await getDbExec().execute({
+      sql: `DELETE FROM text_analyses WHERE id = ?`,
+      args: [id],
+    });
+    return { deleted: id };
+  },
+});
+```
+
+Once these files are saved the dev server picks them up automatically. No
+restart needed. Try listing analyses from the terminal:
+
+```bash
+pnpm action list-text-analyses
+```
+
+You should see an empty array. The table exists and the action works; there's
+just nothing saved yet:
+
+```
+[]
+```
+
+Data is saved to `data/app.db`, a SQLite file in your project directory that
+gets created automatically on first run. In production you'd point
+`DATABASE_URL` at a hosted database instead, but locally this file is all you
+need.
+
+To save something, first run `analyze-text` to get the counts:
+
+```bash
+pnpm action analyze-text --text "Hello world"
+```
+
+You'll see output like:
+
+```
+{
+  title: 'Text statistics',
+  points: [
+    { label: 'Characters', value: 11 },
+    { label: 'Words', value: 2 },
+    { label: 'Sentences', value: 1 },
+    { label: 'Paragraphs', value: 1 }
+  ]
+}
+```
+
+Then pass those values to `save-text-analysis`:
+
+```bash
+pnpm action save-text-analysis \
+  --input "Hello world" \
+  --charCount 11 \
+  --wordCount 2 \
+  --sentenceCount 1
+```
+
+Now run `list-text-analyses` again and you'll see the saved row:
+
+```bash
+pnpm action list-text-analyses
+```
+
+Or ask the agent in the chat at `http://localhost:8080` to do both steps at once:
+
+> Run analyze-text on "Hello world", then save the result.
+
+## What's next {#next}
+
+<Cards>
+
+### [Add a Page](/docs/getting-started-pages)
+
+Build a React route that displays your saved analyses and wire it into the
+sidebar. Next in the series.
+
+### [Database](/docs/database)
+
+Migrations, schema helpers, and production database setup — the full reference
+for SQL in Agent Native.
+
+### [Actions](/docs/actions)
+
+Schemas, auth, approvals, hooks, and transport — the full reference for what
+actions can do.
+
+### [Key Concepts](/docs/key-concepts)
+
+The architecture underneath this tutorial: SQL, actions, live sync, and context
+awareness.
+
+</Cards>

package/docs/content/getting-started-pages.mdx

@@ -0,0 +1,190 @@
+---
+title: "Add a Page"
+description: "Build a React route that displays your saved data and wire it into the sidebar so the agent can navigate to it."
+---
+
+# Add a Page
+
+This is part four of the Getting Started series. In [Persist Data in SQL](/docs/getting-started-database) you saved action results to a database. Here you'll build a page that displays that data and connect it to the sidebar.
+
+## Add a page the agent can open {#add-a-page}
+
+Chat is great for conversational interaction, but some data is better inspected
+in a dedicated UI: a table you can scan, sort, or delete rows from. This step
+adds a React route that displays everything saved in `text_analyses`, using the
+same `list-text-analyses` and `delete-text-analysis` actions you already wrote.
+There's no second data layer. The page is just a view over the same SQL state
+the agent reads and writes.
+
+Create the route file at `app/routes/text-analyses.tsx`. Route files in
+`app/routes/` are automatically picked up by the framework. The filename
+becomes the URL path, so this page will be available at
+`http://localhost:8080/text-analyses`.
+
+```tsx filename="app/routes/text-analyses.tsx"
+import {
+  useActionMutation,
+  useActionQuery,
+} from "@agent-native/core/client/hooks";
+
+export default function TextAnalysesRoute() {
+  const analyses = useActionQuery("list-text-analyses", {});
+  const deleteAnalysis = useActionMutation("delete-text-analysis");
+
+  return (
+    <main className="mx-auto flex max-w-3xl flex-col gap-6 p-6">
+      <header>
+        <h1 className="text-2xl font-semibold">Text analyses</h1>
+        <p className="text-muted-foreground">
+          Results saved by the agent or triggered manually.
+        </p>
+      </header>
+      <section className="flex flex-col gap-3">
+        {analyses.data?.length === 0 && (
+          <p className="text-muted-foreground">No analyses saved yet.</p>
+        )}
+        {analyses.data?.map((row: any) => (
+          <article
+            key={row.id}
+            className="flex items-start justify-between rounded-lg border p-4"
+          >
+            <div className="flex flex-col gap-1">
+              <p className="text-sm font-medium">{row.input}</p>
+              <p className="text-xs text-muted-foreground">
+                {row.word_count} words · {row.char_count} characters ·{" "}
+                {row.sentence_count} sentences
+              </p>
+            </div>
+            <button
+              className="text-xs text-destructive hover:underline"
+              onClick={() => deleteAnalysis.mutate({ id: row.id })}
+            >
+              Delete
+            </button>
+          </article>
+        ))}
+      </section>
+    </main>
+  );
+}
+```
+
+`useActionQuery` calls `list-text-analyses` and keeps the result live. If the
+agent saves a new row while the page is open, it appears automatically.
+`useActionMutation` calls `delete-text-analysis` when the user clicks Delete,
+then invalidates the query so the list refreshes.
+
+Open `http://localhost:8080/text-analyses` in your browser. If you saved an
+analysis in the previous step you'll see it listed. Then ask the agent in chat:
+
+> Open the text analyses page.
+
+If you get a 404, try restarting your dev server.
+
+The agent calls the `navigate` action (already included in the Chat
+template) to send the browser to `/text-analyses`. This is what it looks like
+with a few saved rows:
+
+<WireframeBlock id="doc-block-response-insights-page-wireframe">
+  <Screen
+    surface="desktop"
+    html={
+      "<main style='min-height:400px;box-sizing:border-box;padding:28px;background:var(--wf-bg)'><div style='max-width:720px;margin:0 auto;display:flex;flex-direction:column;gap:20px'><header><h2 style='margin:0 0 4px;font-size:24px;font-weight:600'>Text analyses</h2><p class='wf-muted' style='margin:0;font-size:14px'>Results saved by the agent or triggered manually.</p></header><section style='display:flex;flex-direction:column;gap:10px'><article class='wf-card' data-rough style='display:flex;align-items:center;justify-content:space-between;padding:14px 16px'><div><p style='margin:0 0 4px;font-size:14px;font-weight:500'>Hello world</p><p class='wf-muted' style='margin:0;font-size:12px'>2 words · 11 characters · 1 sentence</p></div><span class='wf-muted' style='font-size:12px'>Delete</span></article><article class='wf-card' data-rough style='display:flex;align-items:center;justify-content:space-between;padding:14px 16px'><div><p style='margin:0 0 4px;font-size:14px;font-weight:500'>The quick brown fox jumps over the lazy dog.</p><p class='wf-muted' style='margin:0;font-size:12px'>9 words · 44 characters · 1 sentence</p></div><span class='wf-muted' style='font-size:12px'>Delete</span></article><article class='wf-card' data-rough style='display:flex;align-items:center;justify-content:space-between;padding:14px 16px'><div><p style='margin:0 0 4px;font-size:14px;font-weight:500'>Pack my box with five dozen liquor jugs.</p><p class='wf-muted' style='margin:0;font-size:12px'>8 words · 40 characters · 1 sentence</p></div><span class='wf-muted' style='font-size:12px'>Delete</span></article></section></div></main>"
+    }
+  />
+</WireframeBlock>
+
+## Extend the navigation {#extend-navigation}
+
+The sidebar's links are a plain array in `app/components/layout/Sidebar.tsx`,
+not a separate config file. Open it and add an entry for the Text analyses
+page next to the existing Chat entry:
+
+```tsx filename="app/components/layout/Sidebar.tsx"
+import { IconList, IconMessageCircle } from "@tabler/icons-react";
+
+const navItems = [
+  {
+    icon: IconMessageCircle,
+    labelKey: "navigation.chat",
+    href: "/",
+    view: "chat",
+  },
+  {
+    icon: IconList,
+    labelKey: "navigation.textAnalyses",
+    href: "/text-analyses",
+    view: "text-analyses",
+  },
+];
+```
+
+`icon` takes an imported Tabler icon component, not a string name. `labelKey`
+looks up a string in the i18n catalog (`app/i18n/en-US.ts` and the other
+locale files); an unregistered key still renders — it falls back to a
+humanized version of the key (`navigation.textAnalyses` becomes "Text
+analyses") — but add it to the catalogs if you want the label translated. See
+[Internationalization](/docs/internationalization).
+
+Save the file. The dev server picks up the change automatically and the sidebar
+updates without a restart.
+
+### Agent navigation
+
+The sidebar link lets users navigate manually. The agent can also open pages on
+its own using two built-in actions that ship with the Chat template:
+
+- **`view-screen`** reads the current route and returns a compact summary of
+  what the user is looking at.
+- **`navigate`** writes a same-origin path to the browser's history.
+
+As you add more pages, keep `navigate` updated so the agent knows what
+destinations exist. Document available paths in `AGENTS.md` so the model can
+reason about them.
+
+When the app has both a full-page chat route and an app page, use the shared chat
+handoff helpers described in [Agent Surfaces](/docs/agent-surfaces#rich-chat):
+`AgentChatSurface`, `AgentSidebar`, `useAgentChatHomeHandoff`,
+`useAgentChatHomeHandoffLinks`, and `chatViewTransition`. That lets the full
+chat slide into the side panel as the page opens, keeping the same thread while
+the user inspects durable data.
+
+## Project structure {#project-structure}
+
+```text
+my-app/
+  actions/         # Agent-callable and UI-callable operations
+  app/             # React routes, pages, and chat surfaces
+  server/          # Nitro server and SQL schema
+  AGENTS.md        # Always-on instructions for the app agent
+  .agents/         # Skills the agent loads when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## What's next {#next}
+
+You've built a complete agentic app: a working chat interface, an action, inline
+rendering, a database, and a page the agent can navigate to. From here:
+
+<Cards>
+
+### [Key Concepts](/docs/key-concepts)
+
+The architecture underneath this tutorial: SQL, actions, live sync, and context
+awareness.
+
+### [Agent Surfaces](/docs/agent-surfaces)
+
+Chat, inline UI, app pages, embedded sidecars, automation, and external agents —
+all the ways your app can surface the agent.
+
+### [Context Awareness](/docs/context-awareness)
+
+`view-screen`, `navigate`, route state, and selected objects — how the agent
+knows what the user is looking at.
+
+### [Deployment](/docs/deployment)
+
+Put your app on your own domain.
+
+</Cards>