@agent-native/core 0.122.3 → 0.123.0

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.

package/corpus/templates/plan/.agents/skills/frontend-design/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: frontend-design
 description: >-
-  Create distinctive, production-grade frontend interfaces with high design
-  quality. Use when building web components, pages, artifacts, posters, or
-  applications (websites, landing pages, dashboards, React components,
-  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
-  creative, polished UI that avoids generic AI aesthetics.
+  Sets the visual direction for a new or redesigned surface, with production
+  quality that avoids generic AI aesthetics. Use when building a new page,
+  app, or marketing surface, defining visual identity, or doing a design pass
+  ("make this look good"). Do not load it for routine UI edits: adding a field
+  to an existing form, fixing spacing, wiring a button, or changing copy.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+local-changes: >-
+  Description narrowed and Verification rescoped deliberately; an upstream sync
+  must not restore the broad auto-load triggers or screenshot-everything step.
 metadata:
   internal: true
 ---
@@ -141,11 +144,22 @@ Avoid:
 
 ## Verification
 
+Match verification effort to the size of the change. For one component, one
+form, one page, or a restyle, run the app's existing checks — formatter,
+`pnpm typecheck`, existing tests — and stop there.
+
+Escalate to browser verification only when the user asks for it, or when the
+change is a multi-step user-visible flow that cannot be confirmed any other
+way. Never author a new Playwright/Puppeteer script, add a browser-automation
+dependency, or stand up an e2e harness to check work the user did not ask you
+to test that way; use an available browser tool, or say what you could not
+verify.
+
 For substantial frontend work:
 
 1. Run the relevant formatter/checks.
 2. Start the dev server when the app needs one.
-3. Verify with browser screenshots at desktop and mobile widths.
+3. Verify with the available browser tooling at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,

package/corpus/templates/plan/.agents/skills/plan-authoring-flow/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: plan-authoring-flow
+description: >-
+  Which Plan command and creation action fits a request — document-first,
+  UI-first, prototype-first, design-first, recap, or visual intake — plus how to
+  raise an existing plan to design fidelity. Use when creating, routing, or
+  re-rendering a plan.
+---
+
+# Plan Authoring Flow
+
+The plan skills carry the shared Wireframe & Canvas and Document Quality cores,
+so those rules are not restated in `AGENTS.md`. When the user critiques a plan's
+look or structure, fix the renderer or the sync-guarded skills (not just one
+stored plan) so the improvement sticks.
+
+## Plan Content
+
+Surface material assumptions only when they change behavior, data, security,
+tests, deployment, or definition of done.
+
+## Wireframe Markup
+
+New canvas wireframes must use `<Screen html={...} />` / `data.html` semantic
+HTML. Nested kit-tree nodes such as `FrameScreen`, `Card`, `Row`, and `Btn` are
+legacy compatibility only and should not be authored for new plans/recaps.
+
+## Normal Planning Flow
+
+`/visual-plan` is the main command. Treat it like the host agent's standard
+planning mode: inspect the codebase, use parallel agents when useful, gather the
+information needed, ask clarifying questions through the host's native
+ask-user-question tools when needed, then call `create-visual-plan` to publish
+the plan. When the user pasted, referenced, or already has a Codex / Claude Code
+/ Markdown plan, keep `/visual-plan` as the command and pass the source text to
+`create-visual-plan` as `planText` so the new review surface builds from what
+they already have.
+
+For UI-first work where the plan leads with product screens, use `/visual-plan`
+and call `create-ui-plan`.
+
+For prototype-first work — when the user needs to operate the behavior before
+implementation — use `/visual-plan` and call `create-prototype-plan`. Prototype
+plans must be functional review surfaces with local state and realistic controls;
+do not pass off static screen-to-screen navigation as a prototype. Keep static
+mocks in the document and use the top viewer for functional review, comments,
+rough/clean mode, dark/light mode, and prototype popout.
+(`create-prototype-plan` is an MCP tool reached from `/visual-plan`, not a
+separate slash command.)
+
+For full-fidelity branded UI design before implementation, use `/visual-plan` and
+call `create-plan-design`. Research the real app shell, `design.md` if present,
+`.fig` brand-kit/design-system data when available, and codebase CSS/Tailwind/
+token signals. Pass high-fidelity bounded HTML/CSS screens for the Design tab,
+stable `data-design-id` attributes for targeted element style edits, and
+transitions only when a matching Prototype tab should be clickable. Treat the
+Design tab as the visual source of truth and the Prototype tab as the same
+direction made interactive. (`create-plan-design` is an MCP tool reached from
+`/visual-plan`, not a separate slash command.)
+
+Treat “higher fidelity,” “pixel-accurate,” “polished mockup,” “production-like,”
+“real design,” and “not a sketch/wireframe” as design-first requests, even when
+the prompt also says “mockup.” For an existing plan, do not create a duplicate:
+call `update-visual-plan` on the same plan id with a
+`set-visual-render-mode` patch using `renderMode: "design"`, and replace or patch
+the affected screen HTML/CSS in the same update. Put scoped styles in each
+screen's `css` field, never in `<style>` tags. Merely switching the viewer-local
+Clean toggle removes rough.js for one browser but does not create a high-fidelity
+artifact.
+
+Use `/visual-recap` when the user wants a high-level review surface for a PR,
+commit, branch, or git diff that already changed. Recaps are reverse plans:
+derive blocks from the real diff, call `create-visual-recap` with the recap
+MDX source, publish it as a review aid, and state that reviewers still need to
+inspect the actual changed lines.
+
+The markdown/document portion should stay close to the plan the agent would
+normally produce. Diagrams, wireframes, mockups, annotations, and an optional
+bottom `question-form` Open Questions block are additive review aids, not a
+separate intake flow.
+
+Do not automatically call `create-visual-questions` from `/visual-plan`. If a
+normal plan has answerable unresolved decisions, keep them in the same plan as a
+bottom `question-form` block with single-choice, multi-choice, or freeform
+questions, recommended options when useful, and wireframe/diagram previews for
+visual directions. If the user explicitly requests a visual intake questionnaire
+before planning, call `create-visual-questions` from `/visual-plan`.
+(`create-visual-questions` is an MCP tool reached from `/visual-plan`, not a
+separate slash command.)
+
+## Related Skills
+
+- **visual-plan** — the canonical `/visual-plan` skill, carrying the shared
+  Wireframe & Canvas and Document Quality cores.
+- **visual-recap** — `/visual-recap` recap generation.
+- **plan-hosted-writes** — session, revision guard, and post-write verification
+  for every plan write this flow performs.
+- **plan-review-recaps** — recap comparison blocks and the PR recap workflow.

package/corpus/templates/plan/.agents/skills/plan-browser-editing/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: plan-browser-editing
+description: >-
+  Which browser surfaces are directly editable and which patch op each one
+  autosaves through — inline prose, local plan folders, review annotation mode,
+  canvas/design elements, and branding. Use when changing plan prose, styles, or
+  wireframe/prototype HTML.
+---
+
+# Browser Editing
+
+- Prose in `rich-text` blocks is edited inline with the shared
+  `RichMarkdownEditor`, autosaved through `update-visual-plan` with
+  `contentPatches: [{ op: "update-rich-text", blockId, markdown }]`.
+- Local `/local-plans/:slug` folders opened from `PLAN_LOCAL_DIR` or a
+  repo-relative `?path=...` use the same Notion-style browser editor, but
+  autosave through `update-local-plan-folder` so changes are written to
+  `plan.mdx`, `canvas.mdx`, and `prototype.mdx` without touching the Plan
+  database.
+- Review annotation mode makes prose temporarily read-only so clicks can pin
+  feedback. Leaving review mode restores inline prose editing.
+- Canvas, artboard, wireframe, diagram, and custom visual edits remain driven by
+  comments, source patches, or structured content patches rather than direct
+  rich-text editing.
+- Design-mode artboards can be element-edited with `update-visual-plan`
+  `contentPatches: [{ op: "update-design-element-style", frameId, blockId,
+elementId, styles }]`. Elements must have `data-design-id` or
+  `data-plan-design-id`; use `patch-wireframe-html` / `patch-prototype-html` for
+  structural or text changes.
+
+## Branding
+
+- The sidebar brand header has a `Customize branding` popover. Treat it as a
+  source-code request, not plan data: local Code mode edits `templates/plan`
+  source directly, while hosted/live surfaces route people to Desktop or
+  Builder for code customization.
+
+## Related Skills
+
+- **plan-comments-and-feedback** — the review/annotation side of these surfaces.
+- **plan-source-sync** — the MDX files local folder autosave writes to.
+- **plan-hosted-writes** — verification required after each hosted write.