Build Verse: a poem-quote app on the agent-native chat template

Adds a Postgres-backed quotes domain (poems/quotes/favorites) exposed as
five agent-native actions (list-quotes, get-random-quote, create-quote,
toggle-favorite, list-favorites) callable from both chat and the React UI
via useActionQuery/useActionMutation. Moves the primary UI from chat to a
mobile-first Quotes/Favorites experience (chat moves to /chat), adds
manual OpenTelemetry instrumentation exporting traces/metrics/logs over
OTLP, and wires a local Docker Postgres for shared state.

actions/create-quote.ts

@@ -0,0 +1,68 @@
+import { defineAction } from "@agent-native/core/action";
+import { eq, and } from "drizzle-orm";
+import { z } from "zod";
+
+import { db, schema } from "../server/db/index.js";
+import { hydrateQuotes } from "../server/lib/quotes.js";
+import { withActionSpan } from "../server/otel.js";
+
+export default defineAction({
+  description:
+    "Submit a new poem quote. Finds the poem by author + title (case-insensitive) or creates it if it doesn't exist yet, then adds the quote under it, marked as user-submitted.",
+  schema: z.object({
+    text: z.string().min(1).describe("The quote text (an excerpt from the poem)"),
+    author: z.string().min(1).describe("The poet's name"),
+    poemTitle: z.string().min(1).describe("Title of the poem this quote is from"),
+    source: z.string().optional().describe("Collection/book the poem was published in"),
+    year: z.coerce.number().int().optional().describe("Year the poem was written or published"),
+    tags: z
+      .array(z.string())
+      .optional()
+      .describe("Theme tags for the quote, e.g. [\"hope\", \"nature\"]"),
+  }),
+  run: async (args) => {
+    return withActionSpan(
+      "create-quote",
+      { author: args.author, poemTitle: args.poemTitle },
+      async () => {
+        const existing = await db()
+          .select()
+          .from(schema.poems)
+          .where(
+            and(
+              eq(schema.poems.author, args.author),
+              eq(schema.poems.title, args.poemTitle),
+            ),
+          )
+          .limit(1);
+
+        let poem = existing[0];
+        if (!poem) {
+          const inserted = await db()
+            .insert(schema.poems)
+            .values({
+              author: args.author,
+              title: args.poemTitle,
+              source: args.source ?? null,
+              year: args.year ?? null,
+            })
+            .returning();
+          poem = inserted[0];
+        }
+
+        const insertedQuote = await db()
+          .insert(schema.quotes)
+          .values({
+            poem_id: poem.id,
+            text: args.text,
+            tags_json: JSON.stringify(args.tags ?? []),
+            is_user_submitted: true,
+          })
+          .returning();
+
+        const [hydrated] = await hydrateQuotes([{ quote: insertedQuote[0], poem }]);
+        return hydrated;
+      },
+    );
+  },
+});

actions/get-random-quote.ts

@@ -0,0 +1,32 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { withActionSpan } from "../server/otel.js";
+import { fetchAllQuoteRows, hydrateQuotes, parseTags } from "../server/lib/quotes.js";
+
+export default defineAction({
+  description:
+    "Get one random poem quote, optionally restricted to a tag. Use for a \"quote of the day\" / discover surface.",
+  schema: z.object({
+    tag: z.string().optional().describe("Only pick from quotes with this tag"),
+    visitorId: z
+      .string()
+      .optional()
+      .describe("Anonymous visitor id, used to mark whether this visitor already favorited the pick"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    return withActionSpan("get-random-quote", { tag: args.tag }, async () => {
+      const rows = await fetchAllQuoteRows();
+      const candidates = args.tag
+        ? rows.filter((row) => parseTags(row.quote.tags_json).includes(args.tag!))
+        : rows;
+
+      if (candidates.length === 0) return null;
+
+      const pick = candidates[Math.floor(Math.random() * candidates.length)];
+      const [hydrated] = await hydrateQuotes([pick], args.visitorId);
+      return hydrated;
+    });
+  },
+});

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}!` };
-  },
-});

actions/list-favorites.ts

@@ -0,0 +1,32 @@
+import { defineAction } from "@agent-native/core/action";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { db, schema } from "../server/db/index.js";
+import { fetchAllQuoteRows, hydrateQuotes } from "../server/lib/quotes.js";
+import { withActionSpan } from "../server/otel.js";
+
+export default defineAction({
+  description: "List all quotes a given visitor has favorited, most recently favorited first.",
+  schema: z.object({
+    visitorId: z.string().min(1).describe("Anonymous visitor id (from browser storage)"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    return withActionSpan("list-favorites", { visitorId: args.visitorId }, async () => {
+      const favorites = await db()
+        .select()
+        .from(schema.favorites)
+        .where(eq(schema.favorites.visitor_id, args.visitorId));
+
+      if (favorites.length === 0) return [];
+
+      const favoritedAt = new Map(favorites.map((f) => [f.quote_id, f.created_at ?? ""]));
+      const allRows = await fetchAllQuoteRows();
+      const rows = allRows.filter((row) => favoritedAt.has(row.quote.id));
+      rows.sort((a, b) => (favoritedAt.get(b.quote.id) ?? "").localeCompare(favoritedAt.get(a.quote.id) ?? ""));
+
+      return hydrateQuotes(rows, args.visitorId);
+    });
+  },
+});

actions/list-quotes.ts

@@ -0,0 +1,65 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { withActionSpan } from "../server/otel.js";
+import { fetchAllQuoteRows, hydrateQuotes, parseTags } from "../server/lib/quotes.js";
+
+export default defineAction({
+  description:
+    "List/browse poem quotes, optionally filtered by tag, author, or a free-text search over the quote and poem title. Set favoritesOnly=\"true\" with visitorId to list only that visitor's favorites (prefer list-favorites for that case though).",
+  schema: z.object({
+    tag: z.string().optional().describe("Only quotes with this tag (e.g. \"hope\", \"nature\")"),
+    author: z.string().optional().describe("Only quotes by this poet (exact match)"),
+    search: z
+      .string()
+      .optional()
+      .describe("Free-text search across quote text and poem title"),
+    visitorId: z
+      .string()
+      .optional()
+      .describe("Anonymous visitor id, used to mark which quotes this visitor has favorited"),
+    favoritesOnly: z
+      .string()
+      .optional()
+      .describe("Pass \"true\" (with visitorId) to only return favorited quotes"),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(200)
+      .optional()
+      .describe("Max quotes to return (default 100)"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    return withActionSpan(
+      "list-quotes",
+      { tag: args.tag, author: args.author, search: args.search },
+      async () => {
+        const rows = await fetchAllQuoteRows();
+        const search = args.search?.trim().toLowerCase();
+
+        const filtered = rows.filter((row) => {
+          if (args.author && row.poem.author !== args.author) return false;
+          if (args.tag && !parseTags(row.quote.tags_json).includes(args.tag)) {
+            return false;
+          }
+          if (search) {
+            const haystack = `${row.quote.text} ${row.poem.title} ${row.poem.author}`.toLowerCase();
+            if (!haystack.includes(search)) return false;
+          }
+          return true;
+        });
+
+        filtered.sort((a, b) => (b.quote.created_at ?? "").localeCompare(a.quote.created_at ?? ""));
+        const limited = filtered.slice(0, args.limit ?? 100);
+
+        let hydrated = await hydrateQuotes(limited, args.visitorId);
+        if (args.favoritesOnly === "true") {
+          hydrated = hydrated.filter((q) => q.isFavorited);
+        }
+        return hydrated;
+      },
+    );
+  },
+});

actions/toggle-favorite.ts

@@ -0,0 +1,54 @@
+import { defineAction } from "@agent-native/core/action";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { db, schema } from "../server/db/index.js";
+import { quoteFavoriteCounter, withActionSpan } from "../server/otel.js";
+
+export default defineAction({
+  description:
+    "Favorite or unfavorite a quote for a given visitor (toggles based on current state). Returns the new favorited state and total favorite count for the quote.",
+  schema: z.object({
+    quoteId: z.coerce.number().int().describe("The quote's id"),
+    visitorId: z.string().min(1).describe("Anonymous visitor id (from browser storage)"),
+  }),
+  run: async (args) => {
+    return withActionSpan(
+      "toggle-favorite",
+      { quoteId: args.quoteId },
+      async () => {
+        const existing = await db()
+          .select()
+          .from(schema.favorites)
+          .where(
+            and(
+              eq(schema.favorites.quote_id, args.quoteId),
+              eq(schema.favorites.visitor_id, args.visitorId),
+            ),
+          )
+          .limit(1);
+
+        let favorited: boolean;
+        if (existing.length > 0) {
+          await db().delete(schema.favorites).where(eq(schema.favorites.id, existing[0].id));
+          favorited = false;
+          quoteFavoriteCounter.add(1, { action: "remove" });
+        } else {
+          await db().insert(schema.favorites).values({
+            quote_id: args.quoteId,
+            visitor_id: args.visitorId,
+          });
+          favorited = true;
+          quoteFavoriteCounter.add(1, { action: "add" });
+        }
+
+        const allFavorites = await db()
+          .select()
+          .from(schema.favorites)
+          .where(eq(schema.favorites.quote_id, args.quoteId));
+
+        return { quoteId: args.quoteId, favorited, favoriteCount: allFavorites.length };
+      },
+    );
+  },
+});