@agent-native/core 0.122.4 → 0.123.1

package/corpus/templates/mail/server/handlers/automations.ts

@@ -1,148 +1,11 @@
-import { readBody, getSession } from "@agent-native/core/server";
-import type { AutomationRule } from "@shared/types.js";
-import { eq, and } from "drizzle-orm";
-import { defineEventHandler, getRouterParam, createError } from "h3";
-import { nanoid } from "nanoid";
+import { getSession } from "@agent-native/core/server";
+import { defineEventHandler, createError } from "h3";
 
-import { db, schema } from "../db/index.js";
 import { triggerAutomationsDebounced } from "../lib/automation-engine.js";
 
-function toApiRule(row: any): AutomationRule {
-  return {
-    id: row.id,
-    ownerEmail: row.ownerEmail,
-    domain: row.domain,
-    name: row.name,
-    condition: row.condition,
-    actions: JSON.parse(row.actions),
-    enabled: row.enabled === 1 || row.enabled === true || row.enabled === "1",
-    createdAt: new Date(Number(row.createdAt)).toISOString(),
-    updatedAt: new Date(Number(row.updatedAt)).toISOString(),
-  };
-}
-
-// ─── List automations ────────────────────────────────────────────────────────
-
-export const listAutomations = defineEventHandler(async (event) => {
-  const session = await getSession(event);
-  if (!session?.email) {
-    throw createError({ statusCode: 401, statusMessage: "Unauthenticated" });
-  }
-  const ownerEmail = session.email;
-
-  const rules = await db
-    .select()
-    .from(schema.automationRules)
-    .where(eq(schema.automationRules.ownerEmail, ownerEmail));
-
-  return rules.map(toApiRule);
-});
-
-// ─── Create automation ───────────────────────────────────────────────────────
-
-export const createAutomation = defineEventHandler(async (event) => {
-  const session = await getSession(event);
-  if (!session?.email) {
-    throw createError({ statusCode: 401, statusMessage: "Unauthenticated" });
-  }
-  const ownerEmail = session.email;
-
-  const body = await readBody(event);
-  const { name, condition, actions, domain = "mail", enabled = true } = body;
-
-  if (!name || !condition || !actions) {
-    throw new Error("name, condition, and actions are required");
-  }
-
-  const now = Date.now();
-  const rule = {
-    id: nanoid(12),
-    ownerEmail,
-    domain,
-    name,
-    condition,
-    actions: JSON.stringify(actions),
-    enabled: enabled ? 1 : 0,
-    createdAt: now,
-    updatedAt: now,
-  };
-
-  await db.insert(schema.automationRules).values(rule as any);
-  return toApiRule(rule);
-});
-
-// ─── Update automation ───────────────────────────────────────────────────────
-
-export const updateAutomation = defineEventHandler(async (event) => {
-  const session = await getSession(event);
-  if (!session?.email) {
-    throw createError({ statusCode: 401, statusMessage: "Unauthenticated" });
-  }
-  const ownerEmail = session.email;
-  const id = getRouterParam(event, "id");
-
-  if (!id) throw new Error("id is required");
-
-  const body = await readBody(event);
-  const updates: Record<string, any> = { updatedAt: Date.now() };
-
-  if (body.name !== undefined) updates.name = body.name;
-  if (body.condition !== undefined) updates.condition = body.condition;
-  if (body.actions !== undefined)
-    updates.actions = JSON.stringify(body.actions);
-  if (body.enabled !== undefined) updates.enabled = body.enabled ? 1 : 0;
-  if (body.domain !== undefined) updates.domain = body.domain;
-
-  await db
-    .update(schema.automationRules)
-    .set(updates)
-    .where(
-      and(
-        eq(schema.automationRules.id, id),
-        eq(schema.automationRules.ownerEmail, ownerEmail),
-      ),
-    );
-
-  // Fetch and return updated rule
-  const [updated] = await db
-    .select()
-    .from(schema.automationRules)
-    .where(
-      and(
-        eq(schema.automationRules.id, id),
-        eq(schema.automationRules.ownerEmail, ownerEmail),
-      ),
-    );
-
-  if (!updated) throw new Error("Rule not found");
-  return toApiRule(updated);
-});
-
-// ─── Delete automation ───────────────────────────────────────────────────────
-
-export const deleteAutomation = defineEventHandler(async (event) => {
-  const session = await getSession(event);
-  if (!session?.email) {
-    throw createError({ statusCode: 401, statusMessage: "Unauthenticated" });
-  }
-  const ownerEmail = session.email;
-  const id = getRouterParam(event, "id");
-
-  if (!id) throw new Error("id is required");
-
-  await db
-    .delete(schema.automationRules)
-    .where(
-      and(
-        eq(schema.automationRules.id, id),
-        eq(schema.automationRules.ownerEmail, ownerEmail),
-      ),
-    );
-
-  return { success: true };
-});
-
-// ─── Trigger automations ─────────────────────────────────────────────────────
+// Automation rule CRUD lives on the action surface (`list-automations`,
+// `create-automation`, `update-automation`, `delete-automation`) backed by
+// ../lib/automations.js. Only the trigger endpoint remains a route.
 
 export const triggerAutomations = defineEventHandler(async (event) => {
   const session = await getSession(event);

package/corpus/templates/mail/server/handlers/emails.ts

@@ -25,7 +25,6 @@ import {
 } from "h3";
 import { nanoid } from "nanoid";
 
-import { normalizeSignature } from "../../shared/signature.js";
 import {
   incrementSendFrequency,
   getContactFrequencyMap,
@@ -68,6 +67,7 @@ import {
   withLocalEmailMutationLock,
   writeLocalEmails as writeEmails,
 } from "../lib/local-email-store.js";
+import { readSettings } from "../lib/mail-settings.js";
 import {
   bodyToHtml as outgoingBodyToHtml,
   buildRawEmail as buildOutgoingRawEmail,
@@ -282,21 +282,6 @@ async function userEmail(event: H3Event): Promise<string> {
   return session.email;
 }
 
-// ─── Settings defaults ──────────────────────────────────────────────────────
-
-const DEFAULT_SETTINGS: UserSettings = {
-  name: "",
-  email: "",
-  signature: "",
-  writingStyle: "",
-  theme: "dark",
-  density: "comfortable",
-  previewPane: "right",
-  sendAndArchive: false,
-  undoSendDelay: 5,
-  tracking: { opens: false, clicks: false },
-};
-
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function reqSource(event: H3Event) {
@@ -364,19 +349,6 @@ async function writeLabels(
   await putUserSetting(email, "labels", { labels }, options);
 }
 
-async function readSettings(email: string): Promise<UserSettings> {
-  const data = await getUserSetting(email, "mail-settings");
-  if (data) {
-    return {
-      ...DEFAULT_SETTINGS,
-      ...(data as any),
-      email: (data as any).email || email,
-      signature: normalizeSignature((data as any).signature),
-    } as UserSettings;
-  }
-  return { ...DEFAULT_SETTINGS, email };
-}
-
 function recomputeUnreadCounts(
   emails: EmailMessage[],
   labels: Label[],
@@ -1854,33 +1826,6 @@ export const listLabels = defineEventHandler(async (_event: H3Event) => {
   return readLabels(email);
 });
 
-// ─── Settings ─────────────────────────────────────────────────────────────────
-
-export const getSettings = defineEventHandler(async (event: H3Event) => {
-  const email = await userEmail(event);
-  return readSettings(email);
-});
-
-export const updateSettings = defineEventHandler(async (event: H3Event) => {
-  const email = await userEmail(event);
-  const current = await readSettings(email);
-  const body = await readBody(event);
-  const updated = {
-    ...current,
-    ...body,
-    ...(body.signature !== undefined
-      ? { signature: normalizeSignature(body.signature) }
-      : {}),
-  };
-  await putUserSetting(
-    email,
-    "mail-settings",
-    updated as Record<string, unknown>,
-    { requestSource: reqSource(event) },
-  );
-  return updated;
-});
-
 // ─── Calendar RSVP ───────────────────────────────────────────────────────────
 
 export const calendarRsvp = defineEventHandler(async (event: H3Event) => {

package/corpus/templates/mail/server/handlers/scheduled-jobs.ts

@@ -1,6 +1,5 @@
 import { readBody, getSession } from "@agent-native/core/server";
 import * as chrono from "chrono-node";
-import { and, eq } from "drizzle-orm";
 import {
   defineEventHandler,
   getRouterParam,
@@ -8,11 +7,7 @@ import {
   type H3Event,
 } from "h3";
 
-import { db, schema } from "../db/index.js";
 import {
-  cancelScheduledJobForOwner,
-  createScheduledJobRecord,
-  listPendingJobs,
   scheduleEmailSend,
   scheduleSnooze,
   sendScheduledJobNowForOwner,
@@ -60,135 +55,6 @@ export function parseNlDate(input: string, timezone: string): Date | null {
 
 // ─── Route Handlers ───────────────────────────────────────────────────────────
 
-/** GET /api/scheduled-jobs — list pending/processing jobs */
-export const listScheduledJobs = defineEventHandler(async (event: H3Event) => {
-  const session = await getSession(event);
-  if (!session?.email) {
-    const { createError } = await import("h3");
-    throw createError({ statusCode: 401, statusMessage: "Unauthenticated" });
-  }
-  return listPendingJobs(session.email);
-});
-
-/** POST /api/scheduled-jobs — create a new job */
-export const createScheduledJob = defineEventHandler(async (event: H3Event) => {
-  const session = await getSession(event);
-  const body = await readBody(event);
-  const { type, emailId, threadId, accountEmail, payload, runAt } = body as {
-    type: "snooze" | "send_later";
-    emailId?: string;
-    threadId?: string;
-    accountEmail?: string;
-    payload?: Record<string, unknown>;
-    runAt: number;
-  };
-
-  if (!type || !runAt) {
-    setResponseStatus(event, 400);
-    return { error: "type and runAt are required" };
-  }
-
-  if (type !== "snooze" && type !== "send_later") {
-    setResponseStatus(event, 400);
-    return { error: "type must be 'snooze' or 'send_later'" };
-  }
-
-  if (!Number.isFinite(runAt) || runAt <= Date.now()) {
-    setResponseStatus(event, 400);
-    return { error: "runAt must be a future timestamp" };
-  }
-
-  if (!session?.email) {
-    setResponseStatus(event, 401);
-    return { error: "Unauthenticated" };
-  }
-  const ownerEmail = session.email;
-  const job = await createScheduledJobRecord({
-    type,
-    ownerEmail,
-    emailId: emailId ?? null,
-    threadId: threadId ?? null,
-    accountEmail: accountEmail ?? (payload as any)?.accountEmail ?? null,
-    payload,
-    runAt,
-  });
-  setResponseStatus(event, 201);
-  return job;
-});
-
-/** PATCH /api/scheduled-jobs/:id — reschedule (update runAt, reset to pending) */
-export const updateScheduledJob = defineEventHandler(async (event: H3Event) => {
-  const session = await getSession(event);
-  if (!session?.email) {
-    setResponseStatus(event, 401);
-    return { error: "Unauthenticated" };
-  }
-  const ownerEmail = session.email;
-  const id = getRouterParam(event, "id");
-  if (!id) {
-    setResponseStatus(event, 400);
-    return { error: "id required" };
-  }
-
-  const body = await readBody(event);
-  const { runAt } = body as { runAt?: number };
-
-  if (!runAt || !Number.isFinite(runAt) || runAt <= Date.now()) {
-    setResponseStatus(event, 400);
-    return { error: "runAt must be a future timestamp" };
-  }
-
-  const [existing] = await db
-    .select()
-    .from(schema.scheduledJobs)
-    .where(
-      and(
-        eq(schema.scheduledJobs.id, id),
-        eq(schema.scheduledJobs.ownerEmail, ownerEmail),
-      ),
-    );
-
-  if (!existing) {
-    setResponseStatus(event, 404);
-    return { error: "Job not found" };
-  }
-
-  await db
-    .update(schema.scheduledJobs)
-    .set({ runAt, status: "pending" } as any)
-    .where(
-      and(
-        eq(schema.scheduledJobs.id, id),
-        eq(schema.scheduledJobs.ownerEmail, ownerEmail),
-      ),
-    );
-
-  return { ...existing, runAt, status: "pending" };
-});
-
-/** DELETE /api/scheduled-jobs/:id — cancel (set status = cancelled) */
-export const deleteScheduledJob = defineEventHandler(async (event: H3Event) => {
-  const session = await getSession(event);
-  if (!session?.email) {
-    setResponseStatus(event, 401);
-    return { error: "Unauthenticated" };
-  }
-  const ownerEmail = session.email;
-  const id = getRouterParam(event, "id");
-  if (!id) {
-    setResponseStatus(event, 400);
-    return { error: "id required" };
-  }
-
-  const cancelled = await cancelScheduledJobForOwner(ownerEmail, id);
-  if (!cancelled) {
-    setResponseStatus(event, 404);
-    return { error: "Job not found" };
-  }
-
-  return { ok: true, job: cancelled };
-});
-
 /** POST /api/scheduled-jobs/:id/send-now — send a pending scheduled email now */
 export const sendScheduledJobNow = defineEventHandler(
   async (event: H3Event) => {

package/corpus/templates/mail/server/lib/aliases.ts

@@ -0,0 +1,18 @@
+import { getUserSetting, putUserSetting } from "@agent-native/core/settings";
+
+import type { Alias } from "../../shared/types.js";
+
+export async function readAliases(email: string): Promise<Alias[]> {
+  const data = await getUserSetting(email, "aliases");
+  if (data && Array.isArray((data as { aliases?: unknown }).aliases)) {
+    return (data as { aliases: Alias[] }).aliases;
+  }
+  return [];
+}
+
+export async function writeAliases(
+  email: string,
+  aliases: Alias[],
+): Promise<void> {
+  await putUserSetting(email, "aliases", { aliases });
+}

package/corpus/templates/mail/server/lib/automations.ts

@@ -0,0 +1,104 @@
+import { and, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+
+import type { AutomationAction, AutomationRule } from "../../shared/types.js";
+import { db, schema } from "../db/index.js";
+
+export function toApiRule(row: any): AutomationRule {
+  return {
+    id: row.id,
+    ownerEmail: row.ownerEmail,
+    domain: row.domain,
+    name: row.name,
+    condition: row.condition,
+    actions: JSON.parse(row.actions),
+    enabled: row.enabled === 1 || row.enabled === true || row.enabled === "1",
+    createdAt: new Date(Number(row.createdAt)).toISOString(),
+    updatedAt: new Date(Number(row.updatedAt)).toISOString(),
+  };
+}
+
+function ownedRule(ownerEmail: string, id: string) {
+  return and(
+    eq(schema.automationRules.id, id),
+    eq(schema.automationRules.ownerEmail, ownerEmail),
+  );
+}
+
+export async function listAutomationRules(
+  ownerEmail: string,
+): Promise<AutomationRule[]> {
+  const rules = await db
+    .select()
+    .from(schema.automationRules)
+    .where(eq(schema.automationRules.ownerEmail, ownerEmail));
+  return rules.map(toApiRule);
+}
+
+export async function createAutomationRule(
+  ownerEmail: string,
+  input: {
+    name: string;
+    condition: string;
+    actions: AutomationAction[];
+    domain?: string;
+    enabled?: boolean;
+  },
+): Promise<AutomationRule> {
+  const now = Date.now();
+  const rule = {
+    id: nanoid(12),
+    ownerEmail,
+    domain: input.domain ?? "mail",
+    name: input.name,
+    condition: input.condition,
+    actions: JSON.stringify(input.actions),
+    enabled: (input.enabled ?? true) ? 1 : 0,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  await db.insert(schema.automationRules).values(rule as any);
+  return toApiRule(rule);
+}
+
+export async function updateAutomationRule(
+  ownerEmail: string,
+  id: string,
+  patch: {
+    name?: string;
+    condition?: string;
+    actions?: AutomationAction[];
+    enabled?: boolean;
+    domain?: string;
+  },
+): Promise<AutomationRule> {
+  const updates: Record<string, any> = { updatedAt: Date.now() };
+  if (patch.name !== undefined) updates.name = patch.name;
+  if (patch.condition !== undefined) updates.condition = patch.condition;
+  if (patch.actions !== undefined) {
+    updates.actions = JSON.stringify(patch.actions);
+  }
+  if (patch.enabled !== undefined) updates.enabled = patch.enabled ? 1 : 0;
+  if (patch.domain !== undefined) updates.domain = patch.domain;
+
+  await db
+    .update(schema.automationRules)
+    .set(updates)
+    .where(ownedRule(ownerEmail, id));
+
+  const [updated] = await db
+    .select()
+    .from(schema.automationRules)
+    .where(ownedRule(ownerEmail, id));
+
+  if (!updated) throw new Error("Rule not found");
+  return toApiRule(updated);
+}
+
+export async function deleteAutomationRule(
+  ownerEmail: string,
+  id: string,
+): Promise<void> {
+  await db.delete(schema.automationRules).where(ownedRule(ownerEmail, id));
+}

package/corpus/templates/mail/server/lib/jobs.ts

@@ -317,6 +317,40 @@ export async function createScheduledJobRecord(input: {
   return job;
 }
 
+export async function updateScheduledJobForOwner(
+  ownerEmail: string,
+  id: string,
+  runAt: number,
+): Promise<ScheduledJobRecord | null> {
+  const [existing] = await db
+    .select()
+    .from(schema.scheduledJobs)
+    .where(
+      and(
+        eq(schema.scheduledJobs.id, id),
+        eq(schema.scheduledJobs.ownerEmail, ownerEmail),
+      ),
+    );
+
+  if (!existing) return null;
+
+  await db
+    .update(schema.scheduledJobs)
+    .set({ runAt, status: "pending" } as any)
+    .where(
+      and(
+        eq(schema.scheduledJobs.id, id),
+        eq(schema.scheduledJobs.ownerEmail, ownerEmail),
+      ),
+    );
+
+  return {
+    ...(existing as ScheduledJobRecord),
+    runAt,
+    status: "pending",
+  };
+}
+
 export async function scheduleSnooze(input: {
   ownerEmail: string;
   emailId: string;

package/corpus/templates/mail/server/lib/mail-settings.ts

@@ -0,0 +1,43 @@
+import { getUserSetting } from "@agent-native/core/settings";
+
+import { normalizeSignature } from "../../shared/signature.js";
+import type { UserSettings } from "../../shared/types.js";
+
+export const DEFAULT_SETTINGS: UserSettings = {
+  name: "",
+  email: "",
+  signature: "",
+  writingStyle: "",
+  theme: "dark",
+  density: "comfortable",
+  previewPane: "right",
+  sendAndArchive: false,
+  undoSendDelay: 5,
+  tracking: { opens: false, clicks: false },
+};
+
+export async function readSettings(email: string): Promise<UserSettings> {
+  const data = await getUserSetting(email, "mail-settings");
+  if (data) {
+    return {
+      ...DEFAULT_SETTINGS,
+      ...(data as Partial<UserSettings>),
+      email: (data as Partial<UserSettings>).email || email,
+      signature: normalizeSignature((data as Partial<UserSettings>).signature),
+    } as UserSettings;
+  }
+  return { ...DEFAULT_SETTINGS, email };
+}
+
+export function mergeSettings(
+  current: UserSettings,
+  patch: Partial<UserSettings>,
+): UserSettings {
+  return {
+    ...current,
+    ...patch,
+    ...(patch.signature !== undefined
+      ? { signature: normalizeSignature(patch.signature) }
+      : {}),
+  };
+}

package/corpus/templates/mail/shared/automation-schema.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+/** Zod mirror of the `AutomationAction` union in `shared/types.ts`. */
+export const automationActionSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("label"), labelName: z.string() }),
+  z.object({ type: z.literal("archive") }),
+  z.object({ type: z.literal("mark_read") }),
+  z.object({ type: z.literal("star") }),
+  z.object({ type: z.literal("trash") }),
+]);

package/corpus/templates/plan/.agents/skills/actions/SKILL.md

@@ -18,6 +18,8 @@ Actions in `actions/` are the **single source of truth** for app operations. The
 
 Before creating any custom REST/API route for app data, inspect `actions/` and the action table in `AGENTS.md`. If an action already exists, call it directly from the agent or with `useActionQuery` / `useActionMutation` from the UI. If the capability is missing, create or update a `defineAction`. Do not add `/api/*`, `server/routes/*`, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.
 
+**Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
@@ -390,12 +392,28 @@ This is the canonical approach for new apps. Action names must be lowercase with
 
 ## When You Still Need Custom `/api/` Routes
 
-Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+This is the complete exception list. A route in `server/routes/api/` is only
+justified when the caller is not your own UI or agent, or when the payload is
+not JSON:
 
 - **File uploads** — actions receive JSON params, not multipart form data
 - **Streaming responses** — SSE or chunked responses that need direct H3 control
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
+- **Public unauthenticated endpoints** — SEO/OG images, share links, and other
+  URLs opened directly by a browser or crawler
+- **Binary or non-JSON responses** — media, exports, generated assets
+
+Everything else is an action: CRUD, settings, search, list/detail reads, auth
+state, and anything the UI fetches as JSON. If a route needs new middleware to
+scope it to the current user, that is a signal it should be an action — actions
+already run inside request context with access checks.
+
+Existing first-party templates still contain a shrinking, explicitly
+grandfathered set of older `/api/*` CRUD routes for app data. The repository's
+`guard:no-action-twin-routes` CI check ratchets that baseline down across the
+first-party template route trees (with the separately owned Plan template
+fenced out); it is not a substitute for keeping generated apps action-first.
 
 When the agent needs a durable image or file URL, call the core `upload-image`
 action or use `uploadFile()` in server code. Do not write base64 into SQL,

package/corpus/templates/plan/.agents/skills/adding-a-feature/SKILL.md

@@ -14,6 +14,8 @@ metadata:
 
 Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
 
+Scope check first: this is the checklist for a feature that adds app data or a new capability. A restyle, a copy change, or a screen with no new data model and no new agent-visible operation only needs the areas it actually touches — do not manufacture actions, state keys, or a skill for it.
+
 ## Why
 
 Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.