@agent-native/core 0.88.0 → 0.90.2

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

@@ -161,6 +161,18 @@ to find likely URLs, `web-request` or `provider-api-docs` with clean
 `webFetch()` when you need to grep, aggregate, or compare many pages before
 returning a small result.
 
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -205,6 +217,49 @@ run: async (args) => {
 }
 ```
 
+### Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
 ### Validating Return Values (`outputSchema`)
 
 `schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.

package/corpus/templates/mail/.agents/skills/contacts-and-crm/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: contacts-and-crm
+description: >-
+  Resolve a name or partial address to a real email and enrich a thread with
+  CRM/contact context (HubSpot, Apollo) before drafting or triaging. Use
+  when the user names a person instead of an email, or asks "who is this"
+  / "what deals/tickets does this contact have".
+---
+
+# Contacts and CRM
+
+## Resolving a recipient
+
+Use `find-contact` before asking the user for someone's email address, and
+before guessing a pattern like `firstinitiallastname@company.com`.
+
+- `find-contact --query="<name or partial email>" --limit=5` matches
+  case-insensitively against name and email, splitting the query into
+  whitespace-separated terms that must ALL match (`"jacqueline lamb"` requires
+  both terms present).
+- Results are sorted by `count`, an interaction-frequency score. Google People
+  API "connections" (explicitly saved contacts) start at `count: 5`; "other
+  contacts" (people the user has emailed but not saved) start lower. Sending
+  or receiving mail increments a real `sendCount`/`receiveCount` in the
+  `contact_frequency` SQL table, so the top match is usually the person the
+  user actually means.
+- If `find-contact` returns zero matches, tell the user — do not invent an
+  email address. A wrong guess either bounces or, worse, silently reaches the
+  wrong inbox.
+- Results are cached per-owner for a few minutes (`contactCache` in
+  `server/handlers/emails.ts`). A contact added in Google Contacts moments ago
+  may not appear immediately; that's expected, not a bug to route around.
+
+## CRM enrichment
+
+- `get-hubspot-contact --email=<address>` is the only first-class CRM action.
+  It returns contact fields (name, phone, company, title, lifecycle stage,
+  lead status) plus up to 5 associated deals and up to 5 associated tickets,
+  reading the user's own HubSpot API key configured in Settings. If no key is
+  configured it returns `{ error: "HubSpot API key not configured" }` —
+  surface that plainly rather than treating it as "no CRM data exists."
+- **Gong, Pylon, and Apollo are UI-only in Mail.** They have server route
+  handlers (`server/handlers/gong.ts`, `pylon.ts`, `apollo.ts`) that power the
+  CRM sidebar panel in the email view, each reading its own per-session API
+  key from `appStateGet`. None of the three is registered in Mail's
+  `MAIL_PROVIDER_API_IDS` (see `listProviderApiIdsForTemplateUse("mail")` in
+  `server/lib/provider-api.ts`, which currently resolves to `gmail`,
+  `google_calendar`, and `hubspot` only). This means:
+  - There is no agent action for Gong calls, Pylon tickets, or Apollo person
+    lookups in Mail.
+  - `provider-api-request` will refuse `provider: "gong"`, `"pylon"`, or
+    `"apollo"` in this app even though those provider ids exist in the shared
+    catalog — they're enabled for other templates (e.g. Analytics), not Mail.
+  - If the user asks the agent to pull a Gong call or Pylon ticket from Mail,
+    say plainly that integration is visible in the UI sidebar only today; do
+    not fabricate a result or imply `provider-api-request` can reach it.
+- For HubSpot data outside contact lookup (deals search, ticket creation,
+  property metadata), use `provider-api-catalog` / `provider-api-docs` with
+  `provider: "hubspot"`, then `provider-api-request` — `get-hubspot-contact`
+  only covers the single "lookup by email" shape.
+
+## Related Skills
+
+- `email-drafts` — use resolved contacts and CRM context when composing.
+- `draft-queue` — resolving the right `ownerEmail` teammate uses
+  `list-org-members`, a separate lookup from `find-contact`.
+- `actions` — the shared provider API pattern for `provider-api-request`.

package/corpus/templates/mail/.agents/skills/draft-queue/SKILL.md

@@ -11,12 +11,46 @@ The draft queue is for teammate-requested emails that need the owner to review b
 
 - Use `queue-email-draft` when a teammate asks the agent to prepare an email for an organization member.
 - The requester and reviewer must both be members of the active organization.
+  `requireQueueContext` throws if there's no active org, or if the caller isn't
+  a member — both surface as plain errors, not empty results.
 - Slack requests should queue drafts, not send raw emails.
 - `queue-email-draft` returns `reviewUrl`; include that URL when replying to Slack so the owner can open the exact draft.
-- Slack intake verifies the sender email via Slack `users.info` when the app has `users:read.email`, and passes verified sender name/email into the agent context.
+- Slack intake verifies the sender email via Slack `users.info` when the app has `users:read.email`, and passes verified sender name/email into the agent context. If that scope is missing, Slack intake cannot resolve a real email and will not queue anything — tell the requester to ask an admin to grant `users:read.email` rather than guessing their address from their Slack display name.
+- `ownerEmail` accepts more than an exact email: `resolveOrgMemberEmail` also
+  matches an unambiguous local-part prefix (e.g. `"jane"` matches
+  `jane@co.com` if she's the only `jane*` member). If more than one member
+  matches the prefix, the action throws listing all org member emails instead
+  of guessing — pass the full email in that case.
 - Use `send-queued-drafts` only when the queued draft owner explicitly asks to send.
 - Use `open-queued-draft` when the user wants to manually tweak a queued draft in the compose panel.
 
+## Status Lifecycle And Access
+
+A queued draft moves through `queued -> in_review -> sent`, or `-> dismissed`
+at any point before `sent`. Rules enforced in `server/lib/queued-drafts.ts`:
+
+- **Ownership is strict.** Only the `ownerEmail` (or an org `owner`/`admin`
+  role) can call `update-queued-draft`, `open-queued-draft`, or
+  `send-queued-drafts` for a given draft — `requireQueuedDraft(id, {ownerOnly:
+  true})` rejects the original requester from editing or sending it, even
+  though they created it.
+- **Sent drafts are frozen.** `updateQueuedDraft` throws
+  `"Sent queued drafts cannot be edited."` if `status` is already `sent` and
+  the caller isn't also setting it to `sent` again. Don't retry an edit on a
+  sent draft — create a new `queue-email-draft` instead.
+- **`open-queued-draft` transitions status to `in_review`** and copies the
+  draft into a real `compose-{id}` application-state entry (auto-appending the
+  *owner's* configured signature, not the requester's). It also blocks
+  opening a draft that is already `sent` or `dismissed`.
+- **`send-queued-drafts --all=true`** sends every `queued` or `in_review` draft
+  assigned to the caller (default limit 50, capped 50) by delegating to the
+  real `send-email` action per draft — each send still requires the standard
+  approval gate. Partial failures are reported per-draft in `{ sent, failed }`
+  rather than aborting the whole batch; report both lists back to the user.
+- Queueing a draft for someone else fires a best-effort in-app notification to
+  the owner (skipped when self-queuing); a failed notify does not fail the
+  queue action itself.
+
 ## Actions
 
 | Action                        | Purpose                                                                 |

package/corpus/templates/mail/.agents/skills/email-drafts/SKILL.md

@@ -1,3 +1,12 @@
+---
+name: email-drafts
+description: >-
+  Create, edit, and send email drafts through compose-{id} application state,
+  manage-draft, and send-email. Use when composing, replying, forwarding,
+  attaching files, applying signatures/writing style, or checking open/click
+  tracking on sent mail.
+---
+
 # Email Drafts
 
 Create, edit, and manage email drafts. Each draft is stored as an application state entry keyed `compose-{id}`. The UI refreshes through the framework polling/query invalidation path and updates the compose panel automatically.
@@ -68,35 +77,32 @@ Before creating or rewriting a draft, read the user's drafting settings with `pn
 
 The compose panel opens automatically when any compose draft exists. When the last draft is deleted, the panel closes.
 
-## Creating a New Draft
-
-Use the manage-draft script or write directly:
+## Use the `manage-draft` action, not raw `writeAppState`
+
+`manage-draft` is the real action surface for compose drafts (`action`:
+`create` | `update` | `delete` | `delete-all`). Prefer it over hand-writing
+`compose-{id}` state directly — it does things a raw write will not:
+
+- **Sanitizes the id.** IDs must match `/^[a-zA-Z0-9_-]{1,64}$/`
+  (`sanitizeDraftId`); an invalid id on create silently falls back to a
+  timestamp-based id instead of failing.
+- **Appends the signature automatically on create** via
+  `appendSignatureToBody(body, signature)`, reading the configured signature
+  from `mail-settings`. This is idempotent (no-ops if the signature text is
+  already in the body) and signature-aware of quoted content — it inserts the
+  signature before any `— On ... wrote:` or `— Forwarded message —` block, not
+  after it. `update` does NOT re-append the signature — only `create` does, so
+  edit calls should not need to touch the signature themselves.
+- **Returns a `deepLink`** (via `link()`) that opens the exact draft in the
+  real Mail compose UI (`embedApp`/`mcpApp` resource with contact autocomplete,
+  attachments, and send controls) — surface this link when running outside the
+  first-party UI (e.g. from an MCP host).
 
 ```bash
 pnpm action manage-draft --action=create --to=jane@example.com --subject="Quick question" --body="Hi Jane,\n\nJust wanted to follow up on..."
-```
-
-Or from code:
-```ts
-import { writeAppState } from "@agent-native/core/application-state";
-await writeAppState("compose-draft1", {
-  id: "draft1",
-  to: "jane@example.com",
-  subject: "Quick question",
-  body: "Hi Jane,\n\nJust wanted to follow up on...",
-  mode: "compose",
-});
-```
-
-## Editing an Existing Draft
-
-Read the current draft, modify it, write it back:
-
-```ts
-import { readAppState, writeAppState } from "@agent-native/core/application-state";
-const draft = await readAppState("compose-draft1");
-draft.body = "Hi Jane,\n\nI refined the draft as requested...";
-await writeAppState("compose-draft1", draft);
+pnpm action manage-draft --action=update --id=draft1 --body="Hi Jane,\n\nI refined the draft as requested..."
+pnpm action manage-draft --action=delete --id=draft1
+pnpm action manage-draft --action=delete-all
 ```
 
 ## Listing All Drafts
@@ -111,13 +117,6 @@ import { listAppState } from "@agent-native/core/application-state";
 const drafts = await listAppState("compose-");
 ```
 
-## Closing a Draft
-
-```ts
-import { deleteAppState } from "@agent-native/core/application-state";
-await deleteAppState("compose-draft1");
-```
-
 ## Attaching Files
 
 The `send-email` action accepts an optional `attachments` array. Each entry must reference a file that was previously uploaded via the media-upload endpoint (`/api/media/upload`). Pass the server-side `filename` (the key returned by the upload endpoint, e.g. `abc123.pdf`), and optionally `originalName` (display name for the recipient) and `mimeType`. The attachment plumbing resolves the file from the upload store (falling back to `data/uploads/`) and includes it as a MIME multipart attachment in the outgoing Gmail message. Files are never sent speculatively — only attach what the user has explicitly provided and confirmed.
@@ -134,6 +133,39 @@ Example:
 }
 ```
 
+Attachments are resolved eagerly, before Gmail is touched: if any referenced
+upload can't be read, `send-email` throws immediately (nothing is sent) rather
+than sending a partial message. If you see that error, the fix is re-uploading
+via the media endpoint, not retrying the same `filename`.
+
+## What Actually Happens on Send
+
+`send-email` requires explicit user intent to send — it is `needsApproval:
+true` and pauses for human approval before the real Gmail call happens. It
+branches on whether the user has a connected Google account:
+
+- **Connected:** resolves an access token (refreshing if the account's
+  `expiry_date` is within 60s), resolves reply threading (`inReplyTo` /
+  `References` headers) by fetching the original message metadata when
+  `replyToId` is set, resolves the sender display name via
+  `resolveGoogleSenderIdentity` (caching the result), builds the raw MIME
+  message, and calls the real Gmail send API.
+- **Not connected (no Google account):** synthesizes a fake sent message and
+  appends it to the user's `local-emails` setting so the UI still shows a
+  "Sent" item — this is a demo/fallback path, not a queued real send. Do not
+  tell the user the email left their real inbox in this mode.
+- **Open/click tracking:** if `mail-settings.tracking.opens` or `.clicks` is
+  enabled, `send-email` rewrites the outgoing body with a tracking pixel and
+  per-link click tokens before building the MIME message, and persists the
+  token map keyed by the real Gmail message id. `get-tracking --id=<messageId>`
+  reads back open count and per-link click stats for a previously sent
+  message; it returns `tracked: false` (not an error) for messages that were
+  sent before tracking was enabled or when tracking is off.
+- Multiple connected Google accounts: `send-email`'s optional `account` param
+  picks the sender; when replying, it also tries each connected account until
+  one can fetch the original message, and uses that account as the sender if
+  `account` wasn't explicit.
+
 ## Important Notes
 
 - The `id` field in the JSON MUST match the `{id}` in the key name (`compose-{id}`)
@@ -144,3 +176,12 @@ Example:
 - When the user asks you to "edit" or "improve" a draft, list drafts first, then read and update the relevant one
 - **When called from the compose Generate button:** the context tells you which draft to update (e.g. `compose-abc123`). Always update THAT entry — do NOT create a new one with a different ID. Read, modify, and write back to the same key.
 - **When drafting from scratch (no compose window open):** create a new entry with any unique ID
+
+- The `id` field in the JSON MUST match the `{id}` in the key name (`compose-{id}`)
+- The UI debounces writes by 300ms — if the user is actively typing, your write will be visible after a brief moment
+- Always use valid JSON with proper escaping (especially newlines in body: use `\n`)
+- Multiple drafts can exist simultaneously — each appears as a tab in the compose panel
+- When the user asks you to "draft" or "compose" an email, write a compose entry — don't use the send API directly
+- When the user asks you to "edit" or "improve" a draft, list drafts first, then read and update the relevant one
+- **When called from the compose Generate button:** the context tells you which draft to update (e.g. `compose-abc123`). Always update THAT entry — do NOT create a new one with a different ID. Read, modify, and write back to the same key.
+- **When drafting from scratch (no compose window open):** create a new entry with any unique ID

package/corpus/templates/mail/AGENTS.md

@@ -4,7 +4,8 @@ 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.
 
-Detailed draft, queue, storage, sync, and UI patterns live in `.agents/skills/`.
+Detailed draft, queue, and contact-resolution patterns live in
+`.agents/skills/`.
 
 ## Core Rules
 
@@ -12,30 +13,113 @@ Detailed draft, queue, storage, sync, and UI patterns live in `.agents/skills/`.
 - 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 CRM endpoint/filter/pagination/API version
-  matters, use `provider-api-catalog`, `provider-api-docs`, and
+  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`.
-- Never send mail unless the user explicitly asks to send. Draft or queue review
-  by default.
-- When drafting, first read mail settings for signature and writing style. Use
-  the configured signature exactly when present; do not invent or duplicate it.
-- For teammate/Slack-originated send requests, queue a draft for the owner to
-  review instead of sending directly.
+  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; the loop pauses for approval on every real send. 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.
 - Never edit the email store to change a draft the user is currently composing;
-  use `compose-{id}` application state or draft actions.
-- After backend mail mutations, refresh the list state/action path so the UI
-  updates.
+  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.
 - 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.
+
+## 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).                                 |
+| `manage-draft`                                                                                                                         | Create/update/delete a `compose-{id}` draft (signature-aware).                         |
+| `send-email`                                                                                                                           | Real send. `needsApproval: true` — always pauses for human 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; 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.                   |
 
 ## Application State
 
 - `navigation` exposes inbox/thread/draft-queue views and selected ids.
-- `compose-{id}` entries represent open compose tabs and draft content.
-- `navigate` moves the UI.
-- Use `get-thread` or equivalent actions for full conversation context.
+- `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
 
@@ -43,5 +127,7 @@ 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.

package/corpus/templates/mail/actions/archive-email.ts

@@ -5,6 +5,11 @@ import { summarizeArchiveFailures } from "@shared/archive-errors.js";
 import { z } from "zod";
 
 import { archiveEmail } from "../server/lib/email-state.js";
+import {
+  gmailBatchModifyByAccount,
+  isConnected,
+} from "../server/lib/google-auth.js";
+import { invalidateThreadCache } from "../server/lib/thread-cache.js";
 
 function userFacingActionError(message: string, statusCode: number): Error {
   const error = new Error(message) as Error & { statusCode: number };
@@ -21,6 +26,12 @@ export default defineAction({
       .string()
       .optional()
       .describe("Specific connected account to use"),
+    accountEmails: z
+      .string()
+      .optional()
+      .describe(
+        "Per-id account emails, comma-separated and positionally matched to --id (bulk UI calls only)",
+      ),
     removeLabel: z
       .string()
       .optional()
@@ -31,6 +42,12 @@ export default defineAction({
       .string()
       .optional()
       .describe("Thread ID hint to skip an extra Gmail API round-trip"),
+    threadIds: z
+      .string()
+      .optional()
+      .describe(
+        "Per-id thread ID hints, comma-separated and positionally matched to --id (bulk UI calls only)",
+      ),
   }),
   run: async (args) => {
     const ids = args.id
@@ -45,20 +62,59 @@ export default defineAction({
     const ownerEmail = getRequestUserEmail();
     if (!ownerEmail) throw new Error("no authenticated user");
 
+    const threadIdList = args.threadIds?.split(",").map((s) => s.trim());
+    const accountEmailList = args.accountEmails
+      ?.split(",")
+      .map((s) => s.trim());
+    const threadIdFor = (i: number) => threadIdList?.[i] || args.threadId;
+    const accountEmailFor = (i: number) =>
+      accountEmailList?.[i] || args.accountEmail;
+
     const results: { id: string; success: boolean; error?: string }[] = [];
 
-    for (const id of ids) {
-      try {
-        await archiveEmail({
-          id,
-          ownerEmail,
-          accountEmail: args.accountEmail,
-          removeLabel: args.removeLabel,
-          threadId: args.threadId,
-        });
+    // Bulk path: one Gmail batchModify call per account instead of one
+    // modify call per message. Only applies when Gmail is connected and the
+    // caller isn't resolving a label-view removeLabel (that needs a
+    // per-message label lookup, see archiveEmail's reconciliation notes).
+    if (
+      ids.length > 1 &&
+      !args.removeLabel &&
+      (await isConnected(ownerEmail))
+    ) {
+      const targets = ids.map((id, i) => ({
+        id,
+        threadId: threadIdFor(i),
+        accountEmail: accountEmailFor(i),
+      }));
+      const { succeeded, failed } = await gmailBatchModifyByAccount(
+        ownerEmail,
+        targets,
+        undefined,
+        ["INBOX"],
+      );
+      const threadIdById = new Map(targets.map((t) => [t.id, t.threadId]));
+      for (const id of succeeded) {
+        const tid = threadIdById.get(id);
+        if (tid) invalidateThreadCache(ownerEmail, tid);
         results.push({ id, success: true });
-      } catch (err: any) {
-        results.push({ id, success: false, error: err?.message ?? "failed" });
+      }
+      for (const f of failed)
+        results.push({ id: f.id, success: false, error: f.error });
+    } else {
+      for (let i = 0; i < ids.length; i++) {
+        const id = ids[i];
+        try {
+          await archiveEmail({
+            id,
+            ownerEmail,
+            accountEmail: accountEmailFor(i),
+            removeLabel: args.removeLabel,
+            threadId: threadIdFor(i),
+          });
+          results.push({ id, success: true });
+        } catch (err: any) {
+          results.push({ id, success: false, error: err?.message ?? "failed" });
+        }
       }
     }