@agent-native/core 0.122.4 → 0.123.1

package/corpus/templates/mail/.agents/skills/sharing/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: sharing
+description: >-
+  Framework-level sharing and privacy for user-authored resources
+  (dashboards, documents, forms, decks, etc.). Use when making a resource
+  table ownable, wiring list/read/update access checks, or dropping the
+  standard share dialog into a template.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Sharing — Private by Default, Explicit Share
+
+## Rule
+
+Any resource a user **creates** (dashboards, documents, forms, decks, compositions, booking links, issues, analyses) is **private to the creator** by default and visible to others only when they have been **explicitly shared** with or when the creator changes visibility to `org` or `public`.
+
+This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
+
+## Concepts
+
+### Three visibility levels
+
+- **`private`** — owner + explicit share grants only. Default.
+- **`org`** — owner + explicit grants + anyone in the same org (read-only).
+- **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
+
+Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+
+### Roles on a share grant
+
+- **`viewer`** — read only.
+- **`editor`** — read + write.
+- **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
+
+### Anonymous public URLs stay separate
+
+Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
+
+## Make a resource ownable
+
+In your template's `server/db/schema.ts`:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const decks = table("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+Then register it **in `server/db/index.ts`** (not the schema file — keeps the schema file free of the `getDb` closure and avoids circular imports):
+
+```ts
+// server/db/index.ts
+import * as schema from "./schema.js";
+import { createGetDb } from "@agent-native/core/db";
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+export const getDb = createGetDb(schema);
+export { schema };
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
+  getDb,
+});
+```
+
+The `type` string is the stable id the UI and actions use. `getDb` is required — the framework-level share actions use it to reach your template's DB.
+
+### Restricting public visibility and cross-org user shares
+
+Some resources should NOT be reachable by an arbitrary authenticated user even with the link, and should NOT be shareable to an email outside the org. Two optional registration flags lock these axes down:
+
+```ts
+registerShareableResource({
+  type: "extension",
+  // ...
+  allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
+  requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+});
+```
+
+- **`allowPublic: false`** — `set-resource-visibility('public')` throws `ForbiddenError`, `accessFilter` / `resolveAccess` treat any stored `'public'` row as private (defense in depth against bad data), and the share popover hides the "Public" option. `list-resource-shares` returns `policy.allowPublic: false` so the UI follows the server.
+- **`requireOrgMemberForUserShares: true`** — `share-resource` looks up `principalId` in `org_members` and `org_invitations` (pending) for the resource's `orgId` and rejects user shares to anyone else. The same flag also pins `principalType: "org"` shares to the resource's own org — sharing to a *different* org would let that org's members run code in the viewer's auth context (same threat model as a public extension). (The flag name is kept for backward compatibility; treat it as "lock both user and org shares to the resource's org".)
+
+Use both for resources that execute code or expose privileged data with the *viewer's* credentials. Extensions ship with both set: an extension's HTML calls actions / SQL / the secrets-injecting proxy as the viewer, so a public or cross-org-shared extension would let a stranger run arbitrary code with someone else's auth context. `scripts/guard-extension-no-public.mjs` (CI + `pnpm prep`) statically enforces that the extension registration keeps both flags set.
+
+Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
+
+## Filter list/read queries
+
+```ts
+import { accessFilter } from "@agent-native/core/sharing";
+
+const rows = await db
+  .select()
+  .from(schema.decks)
+  .where(accessFilter(schema.decks, schema.deckShares));
+```
+
+`accessFilter` admits rows the current user owns, has been shared on, or that the user can reach via `org` visibility. `public` rows are NOT admitted by default — see the visibility section above for why and how to opt in.
+
+## Guard write actions
+
+```ts
+import { assertAccess } from "@agent-native/core/sharing";
+
+export default defineAction({
+  schema: z.object({ id: z.string(), title: z.string() }),
+  run: async (args) => {
+    await assertAccess("deck", args.id, "editor");
+    // ...proceed
+  },
+});
+```
+
+For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
+
+## Create actions must set owner
+
+When inserting a new row, fill `ownerEmail` and `orgId` from the request context:
+
+```ts
+import {
+  getRequestUserEmail,
+  getRequestOrgId,
+} from "@agent-native/core/server/request-context";
+
+const ownerEmail = getRequestUserEmail();
+// Never fall back to a sentinel like "local@localhost" — that pools every
+// unauthenticated write into one shared tenant (see the 2026-04-29 leak and
+// guard-no-localhost-fallback). Throw / 401 when there is no session instead.
+if (!ownerEmail) throw new Error("Not authenticated");
+
+await db.insert(schema.decks).values({
+  id: nanoid(),
+  title,
+  data,
+  ownerEmail,
+  orgId: getRequestOrgId(),
+  // visibility defaults to 'private'
+  // ...
+});
+```
+
+## Drop in the share UI
+
+```tsx
+import { ShareButton } from "@agent-native/core/client/sharing";
+
+// In the resource's header/toolbar:
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+For list views, show `<VisibilityBadge visibility={row.visibility} />` next to each resource.
+
+## Actions available everywhere
+
+The framework auto-mounts these actions in every template — no per-template boilerplate:
+
+| Action                     | Args                                                                           | Purpose                                   |
+| -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link used in the notification email. |
+| `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
+| `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
+| `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |
+
+Both the agent and the UI use these same actions. The agent calls them as tools;
+UI code should use `ShareButton` / `ShareDialog` or the action client hooks
+instead of hand-writing route calls.
+
+## Migration pattern for existing tables
+
+When retrofitting an existing resource table:
+
+1. Add `owner_email`, `org_id`, `visibility` columns (defaults `'local@localhost'`, `NULL`, `'private'`).
+2. Backfill `owner_email` from any prior creator trail; otherwise leave the default.
+3. Add the companion `{type}_shares` table.
+4. Register via `registerShareableResource`.
+5. Update list/read actions to use `accessFilter`.
+6. Update update/delete actions to `assertAccess` with the correct role.
+7. Add `<ShareButton>` to the resource header.
+8. Add `getResourcePath` in the registration so agent-triggered shares can email a direct link even when no UI supplied `resourceUrl`.
+
+## Templates that opt out
+
+Sharing doesn't apply to:
+
+- **Personal-data apps** (mail, macros) — user-scoped by design.
+- **External source-of-truth apps** (issues → Jira, recruiting → Greenhouse) — ACL lives in the upstream system.
+- **Demo/boilerplate** (starter) — no resources.
+
+For these, add a short note to the template's `AGENTS.md` explaining why.
+
+## Analytics (follow-up)
+
+Dashboards and analyses in the `analytics` template currently live in the settings KV store (`u:<email>:dashboard-*` keys), not SQL. Sharing requires either migrating them to SQL tables (then applying this skill) or extending the settings store with a parallel share overlay. This is a tracked follow-up — see the analytics template's `AGENTS.md`.
+
+## Debugging
+
+- `ForbiddenError` from an action means the current user isn't owner / hasn't been shared / can't meet the role bar.
+- If the agent can't see a resource it just created, check that the insert actually set `owner_email` from the request context.
+- If a share doesn't take effect in the UI, confirm the template's `list-*` action uses `accessFilter` — the share rows are there but nothing is reading them yet.

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