@agent-native/core 0.122.3 → 0.123.0

package/corpus/templates/mail/AGENTS.md

@@ -1,163 +1,94 @@
 # Mail — Agent Guide
 
-Mail is an agent-native inbox, drafting, triage, and draft-review app. The agent
-reads messages, helps prioritize, drafts replies, manages queued drafts, and
-updates mail state through actions and application state.
+Mail is an agent-native inbox: read and triage messages, draft and queue
+replies, and update mail state through actions and application state.
 
-Detailed draft, queue, and contact-resolution patterns live in
-`.agents/skills/`.
+Prompt cap ~6,000 chars; put detail in `.agents/skills/*`.
 
-Before building common workspace or agent UI, read `agent-native-toolkit` to
-inventory existing public kits and installed package seams. Use
-`customizing-agent-native` for the configure → compose → eject → propose seam
-ladder.
+## Skills
 
-## Coverage-aware inventory reads
+Read the relevant skill before deeper work:
 
-`list-emails` remains the compatibility list action for the UI and internal
-callers. External MCP callers receive its structured inventory envelope by
-default (or pass `format: "inventory"`). Inventory reads use `accountEmails`
-for an explicit set; the legacy singular `account` alias cannot be combined
-with it. The response reports each account's success, empty result, exhaustion
-or bounded error, so partial coverage must never be described as complete.
-Inventory items are intentionally compact metadata only — use `get-email` or
-`get-thread` only after selecting a specific result when body content is
-needed.
+- `inbox-reads-and-triage` for listing/searching mail, inventory coverage,
+  refreshing after mutations, and bulk unread cleanup.
+- `email-drafts` for composing, signatures, style, attachments, sending,
+  scheduled sends, tracking, and aliases.
+- `draft-queue` for org and Slack draft review/send workflows.
+- `contacts-and-crm` for resolving recipients and CRM reach.
+- `mail-backends` for real Gmail vs synthetic local fallback.
+- `inbox-automations` for automation rules and Gmail-native filters.
+- `provider-api-scans` for raw provider API calls and staged large scans.
+- Before building common workspace or agent UI, read `agent-native-toolkit`;
+  use `customizing-agent-native` for the configure → compose → eject ladder.
+- `actions`, `storing-data`, `real-time-sync`, `security`, `frontend-design`,
+  and `shadcn-ui` for framework work.
 
 ## Core Rules
 
+- Use actions for reads, labels, settings, drafts, queued drafts, filters,
+  scheduling, refresh, and CRM context. Don't edit mail SQL directly unless a
+  skill or action calls for it.
+- Two backends, chosen automatically per user: real Gmail when a Google account
+  is connected, synthetic `local-emails` data otherwise. Call actions the same
+  way either way, and never claim fallback data or a fallback send touched the
+  user's real inbox.
+- Never send mail unless the user explicitly asks. Draft or queue for review by
+  default; `send-email` is `needsApproval: true`. Use `queue-email-draft` for
+  teammate or Slack-originated send requests.
+- Resolve people with `find-contact` before drafting or sending. Never guess an
+  address pattern; if it returns zero matches, tell the user.
+- Read `get-mail-settings` before drafting. Use the configured `signature`
+  exactly when present; never invent one from the user's name or profile.
+- Never edit the email store to change a draft the user is currently composing;
+  use `manage-draft` or the `compose-{id}` application-state key.
+- After backend mail mutations (archive, trash, star, mark-read, move, send),
+  call `refresh-list` unless the action itself writes `refresh-signal`.
+- Inventory reads report per-account success, empty result, exhaustion, or
+  error. Never describe partial account coverage as complete.
+- Provider-specific actions are shortcuts, not capability limits: escalate to
+  `provider-api-catalog` / `-docs` / `-request` when the exact endpoint, filter,
+  pagination, or API version matters.
+- `get-hubspot-contact` is the only first-class CRM action; Gong, Pylon, and
+  Apollo are UI-only in Mail — say so rather than implying
+  `provider-api-request` reaches them. The agent can't configure aliases or
+  provider API keys (Settings UI only).
+- Use `view-screen` when the active thread, message, draft, or queue item is
+  unclear, and `get-thread` for conversation context rather than screen text.
 - 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.
-- Use actions for email reads, labels, settings, drafts, queued drafts, filters,
-  scheduling, refresh, and CRM context. Do not edit mail SQL directly unless a
-  skill/action explicitly calls for it.
-- **Two mail backends, chosen automatically per user.** When the user has a
-  connected Google account (`isConnected(ownerEmail)`), actions call the real
-  Gmail API. When no account is connected, the same actions fall back
-  transparently to synthetic `local-emails` data stored via `getUserSetting` /
-  `putUserSetting`. Never assume Gmail is connected — actions like
-  `search-emails`, `list-emails`, `get-thread`, `get-email`, and `move-email`
-  branch on this internally, so call them the same way either way.
-- `find-contact` (backed by `loadContactsForEmail`, cached ~a few minutes) is
-  the correct way to resolve a name or partial address to an email before
-  drafting or sending. It merges Google People API "connections" (boosted
-  `count += 5`) and "other contacts" with real send/receive history, and is
-  strictly better than guessing a `firstinitiallastname@company.com` pattern.
-  Never guess an email pattern when `find-contact` returns zero matches — tell
-  the user instead.
-- `get-hubspot-contact` is the only first-class CRM action. Gong, Pylon, and
-  Apollo have server-side lookup handlers (used by the UI's CRM sidebar) but
-  are **not** wired to any agent action and are **not** in Mail's
-  `provider-api-request` catalog (`MAIL_PROVIDER_API_IDS` only resolves to
-  `gmail`, `google_calendar`, and `hubspot` — see `listProviderApiIdsForTemplateUse("mail")`
-  in `server/lib/provider-api.ts`). If the user asks about Gong calls or Pylon
-  tickets from the agent chat, say those providers are UI-only in Mail today;
-  do not claim `provider-api-request` can reach them.
-- Treat provider-specific actions as shortcuts, not capability limits. When the
-  exact Gmail, Google Calendar, or HubSpot endpoint/filter/pagination/API
-  version matters, use `provider-api-catalog`, `provider-api-docs`, and
-  `provider-api-request` against the real provider API. For large scans, stage
-  results with `stageAs` and analyze them with `query-staged-dataset`
-  (`list-staged-datasets` / `delete-staged-dataset` manage the scratch rows).
-- Never send mail unless the user explicitly asks to send. Draft or queue
-  review by default. `send-email` has `needsApproval: true` — it is the
-  canonical, intentionally rare use of the human-in-the-loop gate in this
-  framework. An authenticated A2A caller may carry the user's exact chat
-  authorization for one matching send; otherwise the loop pauses for approval.
-  Drafting and queueing are unaffected.
-- When drafting, first read `get-mail-settings` for signature and writing
-  style. Use `signature` exactly when present — draft-writing paths that build
-  a `compose-*` entry (`manage-draft`, `open-queued-draft`) call
-  `appendSignatureToBody` automatically, which is idempotent (skips if the
-  signature is already present) and inserts before any quoted reply/forward
-  content. Never derive a signature from the user's name or connected profile
-  when none is configured.
-- For teammate/Slack-originated send requests, use `queue-email-draft`
-  (`draft-queue` skill), not `send-email` directly. The requester and reviewer
-  must both be members of the active organization; Slack intake resolves the
-  sender's real email via `users.info` (requires `users:read.email` bot scope)
-  before it will queue anything. Managed installs request that scope through
-  the generated OAuth manifest; reconnect an existing Slack install after
-  granting it. Legacy bot-token installs must add the scope in Slack manually.
-- Never edit the email store to change a draft the user is currently composing;
-  use `manage-draft` or the `compose-{id}` application-state key described in
-  `email-drafts`.
-- After backend mail mutations (archive, trash, star, mark-read, move, send),
-  call `refresh-list` so the UI refetches. Actions that already write
-  `refresh-signal` internally (e.g. `mark-thread-read`, `move-email`,
-  `respond-calendar-invite`) don't need a second call.
-- For broad unread cleanup in one account, call `mark-read` once with
-  `scope: "all-unread"`, the exact `accountEmail`, and any protected
-  conversation IDs in `excludeThreadIds`. Do not loop `mark-thread-read` over
-  many conversations. The bulk result's matched, excluded, changed, failure,
-  and remaining-unread counts are the proof of completion.
-- Use `view-screen` when the active thread, selected message, draft, or queue
-  item is unclear.
-- Aliases (Settings → Aliases) and provider API-key connections (Gong, Pylon,
-  Apollo, HubSpot) are managed only through raw `/api/*` routes from the
-  Settings UI — there are no `manage-aliases` or `save-*-key` actions. The
-  agent can read HubSpot data via `get-hubspot-contact` but cannot configure
-  any of these connections on the user's behalf.
+- 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.
 
 ## Action Map
 
-| Action                                                                                                                                 | Purpose                                                                                                                                                                            |
-| -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search-emails` / `list-emails`                                                                                                        | Query across Gmail or local-fallback data by view/query.                                                                                                                           |
-| `get-email` / `get-thread`                                                                                                             | Full body/metadata for one message or thread.                                                                                                                                      |
-| `find-contact`                                                                                                                         | Resolve a name/partial address to a real email.                                                                                                                                    |
-| `get-hubspot-contact`                                                                                                                  | CRM contact + deals + tickets by email (HubSpot only).                                                                                                                             |
-| `create-attachment-upload`                                                                                                             | Mint a five-minute, owner-bound raw-byte upload URL for one local attachment.                                                                                                      |
-| `manage-draft`                                                                                                                         | Create/update/delete a `compose-{id}` draft (signature-aware).                                                                                                                     |
-| `send-email`                                                                                                                           | Real send. `needsApproval: true`; exact authenticated chat grants run once, otherwise it pauses for approval.                                                                      |
-| `queue-email-draft` / `list-queued-drafts` / `update-queued-draft` / `open-queued-draft` / `send-queued-drafts`                        | Teammate/Slack draft-review workflow — see `draft-queue`.                                                                                                                          |
-| `mark-read` / `mark-thread-read` / `star-email` / `archive-email` / `unarchive-email` / `trash-email` / `untrash-email` / `move-email` | Per-message or per-thread state changes. `mark-read` also supports one-account verified bulk unread cleanup with protected-thread exclusions; most call `refresh-list` internally. |
-| `manage-gmail-filters`                                                                                                                 | Provider-native Gmail filters (create/replace/delete).                                                                                                                             |
-| `manage-automations` / `trigger-automations`                                                                                           | Natural-language inbox automation rules.                                                                                                                                           |
-| `respond-calendar-invite`                                                                                                              | Accept/decline/tentative an invite found in Mail.                                                                                                                                  |
-| `get-mail-settings` / `update-mail-settings` / `import-gmail-signature`                                                                | Signature and writing-style settings.                                                                                                                                              |
-| `manage-snippets`                                                                                                                      | List/create/update/delete saved reply snippets insertable from the compose slash menu.                                                                                             |
-| `get-tracking`                                                                                                                         | Open/click stats for a previously sent, tracked message.                                                                                                                           |
-| `provider-api-catalog` / `provider-api-docs` / `provider-api-request`                                                                  | Raw Gmail, Calendar, or HubSpot API calls beyond the canned actions.                                                                                                               |
+| Action | Purpose |
+| --- | --- |
+| `search-emails` / `list-emails` | Query mail by view/query. |
+| `get-email` / `get-thread` | Full body/metadata for a message or thread. |
+| `find-contact` | Resolve a name/partial address to a real email. |
+| `get-hubspot-contact` | HubSpot contact + deals + tickets by email. |
+| `create-attachment-upload` | Short-lived upload URL for an attachment. |
+| `manage-draft` | Create/update/delete a `compose-{id}` draft. |
+| `send-email` | Real send; `needsApproval: true`. |
+| `queue-email-draft` / `list-queued-drafts` / `update-queued-draft` / `open-queued-draft` / `send-queued-drafts` | Teammate/Slack draft review. |
+| `mark-read` / `mark-thread-read` / `star-email` / `archive-email` / `unarchive-email` / `trash-email` / `untrash-email` / `move-email` | Message/thread state; `mark-read` does bulk cleanup. |
+| `send-scheduled-email-now` / `cancel-scheduled-email` | Send or cancel a scheduled send. |
+| `manage-gmail-filters` | Gmail-native filters. |
+| `manage-automations` / `trigger-automations` | Inbox automation rules. |
+| `respond-calendar-invite` | Accept/decline/tentative an invite. |
+| `get-mail-settings` / `update-mail-settings` / `import-gmail-signature` | Signature and writing style. |
+| `manage-snippets` | Saved reply snippets. |
+| `get-tracking` | Open/click stats for a sent message. |
+| `provider-api-catalog` / `provider-api-docs` / `provider-api-request` | Raw Gmail/Calendar/HubSpot API calls. |
+| `refresh-list` | Make the UI refetch. |
 
 ## Application State
 
 - `navigation` exposes inbox/thread/draft-queue views and selected ids.
-- `compose-{id}` entries represent open compose tabs and draft content (see
-  `email-drafts`).
-- `navigate` moves the UI: `view` (`inbox`, `starred`, `sent`, `drafts`,
-  `scheduled`, `archive`, `trash`, `draft-queue`, `settings`), plus `threadId`,
-  `settingsSection` (`drafting`, `automations`, `gmail-filters`, `aliases`,
-  `tracking`, `slack`, `team`), `queuedDraftId`, or `composeDraftId`.
-- Use `get-thread` for full conversation context instead of relying on ambient
-  screen text.
-
-## Scheduling And Automations
-
-- Scheduled sends use job ids prefixed `scheduled-`; `send-scheduled-email-now`
-  and `cancel-scheduled-email` both strip that prefix internally before
-  looking up the job — pass the id as shown to the user either way.
-- `manage-automations` rules match new inbound mail against a natural-language
-  `condition` using AI, then apply `actions` (`label`, `archive`, `mark_read`,
-  `star`, `trash`). Rules run on a per-minute cron automatically;
-  `trigger-automations` forces immediate processing (debounced — a
-  just-triggered run may report "skipped, try again in 30 seconds").
-- Gmail filters (`manage-gmail-filters`) are a distinct, provider-native
-  mechanism from automation rules — filters run inside Gmail itself, apply
-  before automations, and support raw Gmail criteria/actions. Gmail has no
-  filter-update endpoint: the `replace` operation works by creating a new
-  filter and deleting the old one.
-
-## Skills
-
-Read the relevant skill before deeper work:
-
-- `email-drafts` for composing, signatures, style, replies, and scheduling.
-- `draft-queue` for org review/send workflows.
-- `contacts-and-crm` for resolving recipients and enriching a conversation
-  with CRM/contact context before drafting or triaging.
-- `actions`, `storing-data`, `real-time-sync`, `security`, `frontend-design`,
-  and `shadcn-ui` for framework work.
+- `compose-{id}` entries are open compose tabs and draft content.
+- `navigate` moves the UI via `view`, `threadId`, `settingsSection`,
+  `queuedDraftId`, or `composeDraftId`; the accepted values are listed in
+  `inbox-reads-and-triage`.

package/corpus/templates/mail/actions/create-alias.ts

@@ -0,0 +1,36 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { readAliases, writeAliases } from "../server/lib/aliases.js";
+import type { Alias } from "../shared/types.js";
+
+export default defineAction({
+  description: "Create a recipient alias grouping several email addresses.",
+  schema: z.object({
+    name: z.string().describe("Alias display name"),
+    emails: z.array(z.string()).describe("Email addresses in the alias"),
+  }),
+  agentTool: false,
+  run: async (args) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+    if (!args.name?.trim() || !args.emails?.length) {
+      throw new Error("name and emails are required");
+    }
+
+    const aliases = await readAliases(ownerEmail);
+    const now = new Date().toISOString();
+    const alias: Alias = {
+      id: nanoid(10),
+      name: args.name.trim(),
+      emails: args.emails,
+      createdAt: now,
+      updatedAt: now,
+    };
+    aliases.push(alias);
+    await writeAliases(ownerEmail, aliases);
+    return alias;
+  },
+});

package/corpus/templates/mail/actions/create-automation.ts

@@ -0,0 +1,28 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { createAutomationRule } from "../server/lib/automations.js";
+import { automationActionSchema } from "../shared/automation-schema.js";
+
+export default defineAction({
+  description: "Create an inbox automation rule from the Settings UI.",
+  schema: z.object({
+    name: z.string().describe("Rule name"),
+    condition: z.string().describe("Natural-language match condition"),
+    actions: z
+      .array(automationActionSchema)
+      .describe("Actions applied when the condition matches"),
+    domain: z.enum(["mail", "calendar"]).optional().describe("Rule domain"),
+    enabled: z.boolean().optional().describe("Whether the rule starts enabled"),
+  }),
+  agentTool: false,
+  run: async (args) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+    if (!args.name || !args.condition || !args.actions) {
+      throw new Error("name, condition, and actions are required");
+    }
+    return createAutomationRule(ownerEmail, args);
+  },
+});

package/corpus/templates/mail/actions/create-scheduled-job.ts

@@ -0,0 +1,45 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { createScheduledJobRecord } from "../server/lib/jobs.js";
+
+export default defineAction({
+  description:
+    "Create a scheduled job (snooze or send_later) that runs at a future timestamp.",
+  schema: z.object({
+    type: z.enum(["snooze", "send_later"]).describe("Kind of scheduled job"),
+    emailId: z.string().optional().describe("Email the job applies to"),
+    threadId: z.string().optional().describe("Thread the job applies to"),
+    accountEmail: z
+      .string()
+      .optional()
+      .describe("Connected account the job runs against"),
+    payload: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe("Job-specific payload"),
+    runAt: z.coerce.number().describe("Epoch milliseconds to run the job at"),
+  }),
+  agentTool: false,
+  run: async (args) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+    if (!Number.isFinite(args.runAt) || args.runAt <= Date.now()) {
+      throw new Error("runAt must be a future timestamp");
+    }
+
+    return createScheduledJobRecord({
+      type: args.type,
+      ownerEmail,
+      emailId: args.emailId ?? null,
+      threadId: args.threadId ?? null,
+      accountEmail:
+        args.accountEmail ??
+        (args.payload?.accountEmail as string | undefined) ??
+        null,
+      payload: args.payload,
+      runAt: args.runAt,
+    });
+  },
+});

package/corpus/templates/mail/actions/delete-alias.ts

@@ -0,0 +1,26 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { readAliases, writeAliases } from "../server/lib/aliases.js";
+
+export default defineAction({
+  description: "Delete a recipient alias.",
+  schema: z.object({
+    id: z.string().describe("Alias id"),
+  }),
+  http: { method: "DELETE" },
+  agentTool: false,
+  run: async (args) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+
+    const aliases = await readAliases(ownerEmail);
+    const remaining = aliases.filter((a) => a.id !== args.id);
+    if (remaining.length === aliases.length) {
+      throw new Error("Alias not found");
+    }
+    await writeAliases(ownerEmail, remaining);
+    return { ok: true, id: args.id };
+  },
+});

package/corpus/templates/mail/actions/delete-automation.ts

@@ -0,0 +1,21 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { deleteAutomationRule } from "../server/lib/automations.js";
+
+export default defineAction({
+  description: "Delete an inbox automation rule from the Settings UI.",
+  schema: z.object({
+    id: z.string().describe("Rule id"),
+  }),
+  http: { method: "DELETE" },
+  agentTool: false,
+  run: async ({ id }) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+    if (!id) throw new Error("id is required");
+    await deleteAutomationRule(ownerEmail, id);
+    return { success: true };
+  },
+});

package/corpus/templates/mail/actions/get-automation-settings.ts

@@ -0,0 +1,32 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { getSetting, getUserSetting } from "@agent-native/core/settings";
+import { z } from "zod";
+
+export default defineAction({
+  description:
+    "Read the engine and model used to evaluate inbox automation rules, falling back to the app's configured agent engine.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  agentTool: false,
+  run: async () => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+
+    const data = (await getUserSetting(ownerEmail, "automation-settings")) as {
+      engine?: string;
+      model?: string;
+    } | null;
+    const agentEngine = (await getSetting("agent-engine").catch(
+      () => null,
+    )) as {
+      engine?: string;
+      model?: string;
+    } | null;
+
+    return {
+      engine: data?.engine || agentEngine?.engine || "anthropic",
+      model: data?.model || agentEngine?.model || "claude-haiku-4-5-20251001",
+    };
+  },
+});

package/corpus/templates/mail/actions/get-mail-preferences.ts

@@ -0,0 +1,18 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { readSettings } from "../server/lib/mail-settings.js";
+
+export default defineAction({
+  description:
+    "Read the full mail preferences object backing the Settings UI (appearance, reading, tracking, and drafting fields). Agents should use get-mail-settings for signature and writing style.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  agentTool: false,
+  run: async () => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthorized");
+    return readSettings(ownerEmail);
+  },
+});

package/corpus/templates/mail/actions/list-aliases.ts

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { readAliases } from "../server/lib/aliases.js";
+
+export default defineAction({
+  description: "List the user's saved recipient aliases (Settings → Aliases).",
+  schema: z.object({}),
+  http: { method: "GET" },
+  agentTool: false,
+  run: async () => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+    return readAliases(ownerEmail);
+  },
+});

package/corpus/templates/mail/actions/list-automations.ts

@@ -0,0 +1,18 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { listAutomationRules } from "../server/lib/automations.js";
+
+export default defineAction({
+  description:
+    "List the user's inbox automation rules as structured rows for the Settings UI.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  agentTool: false,
+  run: async () => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+    return listAutomationRules(ownerEmail);
+  },
+});

package/corpus/templates/mail/actions/list-scheduled-jobs.ts

@@ -0,0 +1,18 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { listPendingJobs } from "../server/lib/jobs.js";
+
+export default defineAction({
+  description:
+    "List the user's pending and processing scheduled jobs (snoozes and scheduled sends).",
+  schema: z.object({}),
+  http: { method: "GET" },
+  agentTool: false,
+  run: async () => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+    return listPendingJobs(ownerEmail);
+  },
+});

package/corpus/templates/mail/actions/update-alias.ts

@@ -0,0 +1,37 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { readAliases, writeAliases } from "../server/lib/aliases.js";
+
+export default defineAction({
+  description:
+    "Rename a recipient alias or replace the addresses it expands to.",
+  schema: z.object({
+    id: z.string().describe("Alias id"),
+    name: z.string().optional().describe("New alias display name"),
+    emails: z
+      .array(z.string())
+      .optional()
+      .describe("Replacement list of email addresses"),
+  }),
+  http: { method: "PUT" },
+  agentTool: false,
+  run: async (args) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+
+    const aliases = await readAliases(ownerEmail);
+    const idx = aliases.findIndex((a) => a.id === args.id);
+    if (idx === -1) throw new Error("Alias not found");
+
+    aliases[idx] = {
+      ...aliases[idx],
+      ...(args.name !== undefined ? { name: args.name.trim() } : {}),
+      ...(args.emails !== undefined ? { emails: args.emails } : {}),
+      updatedAt: new Date().toISOString(),
+    };
+    await writeAliases(ownerEmail, aliases);
+    return aliases[idx];
+  },
+});

package/corpus/templates/mail/actions/update-automation-settings.ts

@@ -0,0 +1,33 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { getUserSetting, putUserSetting } from "@agent-native/core/settings";
+import { z } from "zod";
+
+export default defineAction({
+  description:
+    "Set the engine and model used to evaluate inbox automation rules.",
+  schema: z.object({
+    engine: z.string().optional().describe("Agent engine id"),
+    model: z.string().optional().describe("Model id for that engine"),
+  }),
+  http: { method: "PUT" },
+  agentTool: false,
+  run: async (args) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+
+    const existing =
+      ((await getUserSetting(ownerEmail, "automation-settings")) as {
+        engine?: string;
+        model?: string;
+      } | null) || {};
+    const updated = {
+      ...existing,
+      ...(args.engine ? { engine: args.engine } : {}),
+      ...(args.model ? { model: args.model } : {}),
+    };
+    await putUserSetting(ownerEmail, "automation-settings", updated);
+
+    return { success: true, engine: updated.engine, model: updated.model };
+  },
+});

package/corpus/templates/mail/actions/update-automation.ts

@@ -0,0 +1,33 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { updateAutomationRule } from "../server/lib/automations.js";
+import { automationActionSchema } from "../shared/automation-schema.js";
+
+export default defineAction({
+  description:
+    "Update an inbox automation rule from the Settings UI. Only the supplied fields change.",
+  schema: z.object({
+    id: z.string().describe("Rule id"),
+    name: z.string().optional().describe("Rule name"),
+    condition: z
+      .string()
+      .optional()
+      .describe("Natural-language match condition"),
+    actions: z
+      .array(automationActionSchema)
+      .optional()
+      .describe("Replacement action list"),
+    enabled: z.boolean().optional().describe("Whether the rule is enabled"),
+    domain: z.enum(["mail", "calendar"]).optional().describe("Rule domain"),
+  }),
+  http: { method: "PUT" },
+  agentTool: false,
+  run: async ({ id, ...patch }) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Unauthenticated");
+    if (!id) throw new Error("id is required");
+    return updateAutomationRule(ownerEmail, id, patch);
+  },
+});