Email Triage

Experimental

GAIA email triage agent — read, triage, organize, and reply to Gmail/Outlook locally

Install with npm below, then drive it from your app. View on npm →

Install

Runs on: Windows x64Linux x64macOS (Apple Silicon)

@amd-gaia/agent-email

· contract SCHEMA_VERSION 2.3 · last updated 2026-07-10

Eval scorecard (v0.3.0): aggregate 83.4 / 100 — within-one-bucket acceptance accuracy (3-run mean, 95% CI [82.1, 84.7]) over the full 249-email labeled corpus (SCORECARD.md). Triage priority is ordinal, so the bar (#1437) credits exact-or-adjacent buckets — what users feel — not exact 4-way match (reported as a secondary, 0.77). The linked scorecard carries the full recipe, metrics + reported secondaries, run-to-run variance/CI, a per-category breakdown, the run environment, and a worked recomputation; EVALUATION.md is the companion guide — what's measured, the dataset, a worked example, and step-by-step reproduction.

Embed the GAIA email agent in your JS/TS app. It triages, organizes, replies to, and schedules from Gmail and Outlook — with every email body analyzed locally on AMD Ryzen AI via Lemonade. No message content is sent to a cloud LLM; local-only inference is enforced at startup.

This package is the client: a typed EmailClient, a build-time fetcher that downloads and SHA-256-verifies the right native binary for your platform, and helpers to spawn, health-check, and shut down the sidecar. It ships no Python — the agent runs as a frozen, self-contained REST sidecar your app launches and owns.

Using an AI coding assistant? This package ships a SKILL.md — load it into Claude Code (or similar) for a focused, copy-paste integration playbook.

What the agent does

Triage — classify each message (urgent / needs-response / FYI / promotional / personal), summarize a thread, and extract action items and phishing signals. Extracted action items also persist as a local task list linked back to the source message, de-duplicated on re-triage.
Organize — archive, label, move, mark read/unread — one message or in batches.
Reply & send — draft context-aware replies and forwards, then send — attachments included (schema 2.2): triage exposes attachment metadata, and draft/send accept base64 file payloads. In the agent tool loop it can also draft in the user's own voice (a local style profile learned from Sent mail, #1607), schedule a confirmed send for a future time, and snooze messages out of the inbox — agent-loop capabilities today, not yet on this package's REST surface.
Track — flag sent mail still awaiting a reply past a configurable window (follow-up tracking, #1606; detection only — it never auto-sends a nudge) and run a scheduled daily inbox briefing.
Calendar — detect meeting requests, flag conflicts, RSVP, and create events from an email.
Safe by construction — email bodies are treated as untrusted data, never instructions, and anything that leaves the mailbox (send, delete, RSVP) asks for confirmation.

Triage and draft analyze the content you pass and need only the local LLM. Reading or acting on a live mailbox (send, archive, label, calendar) goes through the Google or Microsoft connector (OAuth, configured in GAIA).

How it works

@amd-gaia/agent-email architecture — your Node code spawns and drives a frozen email-agent sidecar (127.0.0.1:8131) over HTTP, which runs triage inference on a local Lemonade Server; a browser/Electron renderer drives the same sidecar over HTTP via the ./client entry.

Three tiers, all on the user's machine — no cloud, no separate GAIA install:

Your app (Node) fetches and spawns the sidecar via the . entry and owns its lifecycle (shutdown() tears it down).
The sidecar is a frozen email-agent binary serving the email REST API — no Python on the host.
Lemonade Server is the one runtime dependency: the sidecar calls a local Lemonade for inference. With none reachable, triage returns HTTP 502.

Once it's running, any Node process can drive it over local HTTP. A browser or Electron renderer reaches it through your app's main process — the sidecar is same-origin only (no CORS), so a renderer can't call it cross-origin directly (see Browser / Electron).

Install

npm install @amd-gaia/agent-email

Corporate TLS: if install fails with UNABLE_TO_GET_ISSUER_CERT behind a proxy, use Node's system CA store: NODE_OPTIONS=--use-system-ca npm install (Node ≥ 22).

Quick start

import { fetchBinary, startSidecar, shutdown } from "@amd-gaia/agent-email";

// Build-time: download + SHA-256-verify the binary for this platform.
const { binaryPath } = await fetchBinary({ outDir: "resources" });

// Runtime: spawn -> wait for /health -> version-check.
const sidecar = await startSidecar({ binaryPath, port: 8131 });

// Drive it with the typed client.
const res = await sidecar.client.triage({
  payload: {
    kind: "single",
    principal: { email: "me@example.com" },
    message: {
      message_id: "m1",
      from: { name: "Sarah Chen", email: "sarah@example.com" },
      subject: "Prod incident follow-up",
      body: "Please review the report and reply by Friday.",
    },
  },
});
console.log(res.result.category, res.result.summary);

await shutdown(sidecar); // kills the whole process tree

Triage many at once

triageBatch sends up to 100 emails or threads in a single request and returns a parallel results array (one entry per item, order-preserved). It's additive — the single triage() above is unchanged. Per-item failures are isolated, so an HTTP 200 can still carry errored items: inspect each results[].error, never just the status.

const batch = await sidecar.client.triageBatch({
  items: [
    {
      kind: "single",
      principal: { email: "me@example.com" },
      message: { message_id: "m1", from: { email: "sarah@example.com" },
        subject: "Prod incident", body: "Reply by Friday." },
    },
    {
      kind: "single",
      principal: { email: "me@example.com" },
      message: { message_id: "m2", from: { email: "promo@shop.example" },
        subject: "Sale", body: "Shop now." },
    },
  ],
});
for (const item of batch.results) {
  if (item.error) console.warn(`item ${item.index} failed: ${item.error.message}`);
  else console.log(`item ${item.index}:`, item.result!.category);
}

Browser / Electron renderer

The . entry uses Node built-ins, so it can't be bundled for a browser or an Electron renderer. The sidecar also serves same-origin only — it sends no CORS headers — so a renderer on a different origin (file://, a dev server, an app:// scheme) cannot call http://127.0.0.1:8131 directly; the browser blocks it. Don't design around a direct renderer→sidecar fetch.

Recommended (Electron): spawn and own the sidecar in your main process via the . entry, and expose triage/draft to the renderer over your own IPC. The renderer never touches the sidecar.

The browser-safe ./client entry (zero Node built-ins, so it bundles for a renderer) is for the case where the renderer does have a same-origin or app-proxied path to the sidecar:

import { EmailClient } from "@amd-gaia/agent-email/client";

// Only from a same-origin page, or behind a proxy you control — not a
// cross-origin fetch straight at 127.0.0.1:8131. Pass the sidecar's session
// token (see Authentication) — get it from your main process via IPC; the
// renderer never spawns the sidecar itself.
const client = new EmailClient({
  baseUrl: "http://127.0.0.1:8131",
  authToken, // from sidecar.authToken in the main process
});
const res = await client.triage({ payload: { /* … */ } });

Authentication

The sidecar binds 127.0.0.1 and can send mail as the user, so it authenticates its caller (#1706). This is separate from the draft→send confirmation_token, which binds a send to one exact message but does not identify who is calling.

Per-session bearer token. spawnSidecar / startSidecar mint a cryptographically-random token, hand it to the sidecar over the private GAIA_EMAIL_SIDECAR_TOKEN env channel, and bind it to sidecar.client. Every /v1/email/* request must carry Authorization: Bearer <token> or the sidecar returns HTTP 401. Using sidecar.client you get this for free; a client you construct yourself must pass authToken (read it from sidecar.authToken).
Host / Origin allowlist. A non-loopback Host header → 400 (DNS-rebinding); a non-loopback browser Origin → 403 (drive-by web page). No permissive CORS is ever sent.

const sidecar = await startSidecar({ binaryPath, port: 8131 });
sidecar.authToken; // the per-session token, if you need to forward it (e.g. IPC)
await sidecar.client.draft({ to: [{ email: "a@b.com" }], subject: "Re: x", body: "hi" });
// A raw client without the token is refused:
new EmailClient({ baseUrl: sidecar.baseUrl }).send(/* … */); // → HttpError 401

Liveness/version probes (/health, /version) and the HTML pages (/v1/email/spec, /v1/email/playground) are exempt from the token.

Prerequisites

The package fetches and spawns the binary, but it does not provision the model. Before any LLM call succeeds, the host needs:

A running Lemonade Server — lemonade-server serve.
The model pulled — via gaia init (installs Lemonade and downloads the default model, Gemma-4-E4B-it-GGUF).

On a fresh machine the binary boots fine, but the first triage returns HTTP 502 until Lemonade and the model are in place. health() is liveness-only — a green /health means the REST surface is up, not that triage will work.

To check actual readiness before your first triage, call client.init() (GET /v1/email/init, #1795) — it probes Lemonade reachability + version + the triage model and returns the InitResponse on both the ready (200) and not-ready (503) paths, so branch on .ready / read .hint instead of catching an error. As a client method it attaches the per-session bearer token for you (a raw fetch would have to add Authorization: Bearer ${sidecar.authToken} itself). POST /v1/email/init can then ask the running Lemonade to pull the model, streaming progress. See SPEC.md → Readiness vs liveness.

Interface

You drive everything through the typed EmailClient — sidecar.client after startSidecar, or constructed directly against a running sidecar (see the renderer example above). Every non-2xx response throws HttpError (with status, url, bodyText) — never a silent null.

Call	Needs	Does
`triage(req)`	Local LLM only	Classifies the message you pass, summarizes it, and extracts action items + spam/phishing signals. No mailbox is read. Action items also persist to the sidecar's local task list, linked to the `message_id` and de-duplicated per message — the response shape is unchanged.
`triageBatch(req)`	Local LLM only	Same as `triage`, but for an `items` array (1–100). Returns a parallel `results` array; per-item failures isolate (HTTP 200 can carry errored items — inspect `results[].error`).
`search(req)`	A connected Gmail/Outlook mailbox	Searches the connected inbox (read-only) by Gmail-style `query`/`labels` and returns message metadata — id, subject, sender, snippet, labels. No message is read in full or modified; no confirmation token needed.
`prescan(req?)`	A connected Gmail/Outlook mailbox	Reads recent inbox messages and returns the triage-card envelope (urgent / needs-response / suggested-archive rows + an informational count). Read-only — nothing is archived, marked, or sent.
`draft(req)`	Nothing external	Proposes a reply (`to` is a list of `{ email }` objects, not strings) and returns a single-use confirmation token. Optional `attachments` (schema 2.2): `{ filename, mime_type, content_base64 }` each, ≤ 25 MB decoded — the token binds to their content digests.
`send(req)`	A connected Gmail/Outlook mailbox + the token	Actually transmits the mail, attachments included. Must carry the exact attachment set the token was minted for — a swapped file or a smuggled extra is rejected with 403.
`confirmAction(req)`	Nothing external	Mints a single-use token for a destructive action (`"archive"` / `"quarantine"`), bound to that exact `(action, message_id)`.
`archive(req)`	A connected mailbox + the token	Removes the message from the inbox. Returns a `batch_id` undo handle.
`unarchive(req)`	A connected mailbox	Restores an archived message within the 30s window (ungated — pass the `batch_id`).
`quarantine(req)`	A connected Gmail mailbox + the token	Applies the `GAIA_PHISHING_QUARANTINE` label + archives a phishing message. Refuses `is_phishing: false`; Gmail-only (an Outlook mailbox → 400, since label-undo can't reverse a folder move).
`unquarantine(req)`	A connected mailbox	Restores a quarantined message's prior labels within the 30s window (ungated — pass the `action_id`).
`listCalendarEvents(opts?)`	A connected mailbox + calendar scope	Views events on the primary calendar (read-only). Optional `timeMin`/`timeMax` RFC 3339 bounds; `provider` only when >1 account is connected.
`previewCalendarEvent(req)`	Nothing external	Mints a single-use confirmation token bound to a proposed event — the calendar analogue of `draft`.
`createCalendarEvent(req)`	A connected mailbox + calendar scope + the token	Creates the event. Requires the token from `previewCalendarEvent`; a missing/invalid token is rejected with 403 before any backend call.
`respondToCalendarEvent(req)`	A connected mailbox + calendar scope	RSVPs `accepted`/`declined`/`tentative` to an existing invite.

triage, draft, confirmAction, and previewCalendarEvent are standalone — you can build and verify those flows with zero connector setup. The read-only search and prescan need a connected mailbox (they read the live inbox) but no confirmation token (503 with none connected, 400 with two). The mutating calls — send, archive, quarantine, and createCalendarEvent — are different on two counts: each requires a single-use confirmation token (call draft for send, confirmAction for archive/quarantine, or previewCalendarEvent for createCalendarEvent; a missing/invalid token is rejected with 403 before anything else), and each acts on the mailbox connected in GAIA on the host (under Settings → Connectors) — so even with a valid token, a headless server returns HTTP 503 until a mailbox is connected.

Scheduled daily briefing (#1608)

The sidecar can generate the prescan triage card on a daily schedule — no prompt, no caller. Off by default; opt in with env vars when launching:

const sidecar = await startSidecar({
  binaryPath,
  env: {
    GAIA_EMAIL_BRIEFING_ENABLED: "true",
    GAIA_EMAIL_BRIEFING_TIME: "08:00", // 24h local HH:MM (default 08:00)
    GAIA_EMAIL_BRIEFING_MAX_MESSAGES: "25", // 1–100 (default 25)
  },
});

Each run persists the email_pre_scan envelope with a generated_at stamp; pull the latest one from GET /v1/email/briefing (plain fetch — no client wrapper yet, so attach the per-session bearer token yourself). It returns 404 until the first scheduled run has happened, and an invalid env value fails sidecar startup loudly rather than guessing a schedule. archive/quarantine are reversible within a 30-second window via unarchive/unquarantine (which are not gated — they restore, never destroy); the calendar actions additionally need the account's calendar scope (a missing scope fails loud with 403 and the reconnect CTA). For a server integration, treat the standalone calls as your surface and handle the mailbox/calendar-mutating calls where a connector is available.

Lifecycle

startSidecar({ binaryPath, port }) runs spawn → health-check → version-check in one call and cleans up if any step fails (so a failed start never leaks a process). When you need finer control, the steps are exported individually:

Helper	Purpose
`fetchBinary(opts)`	Download + SHA-256-verify the platform binary (build time).
`spawnSidecar(opts)`	Launch the binary on `127.0.0.1:<port>` (default `8131`).
`waitForHealth(baseUrl)`	Poll `/health` until live; throws on timeout.
`checkVersion(client)`	Throw if the sidecar's contract MAJOR differs from the client's.
`shutdown(sidecar)`	Kill the whole process tree.

As of SCHEMA_VERSION 2.2 this package exposes inbox search (read-only), the archive / phishing-quarantine mailbox actions (+ their undo), calendar view / create / respond, and attachments (#1542: triage exposes metadata, draft/send accept files). The remaining mailbox actions (label, move, mark read/unread) are part of the full agent but not yet exposed through this package — see SPEC.md for the complete surface.

Stateful agent surface (`/v1/email/agent/*`, 0.4.0)

The typed client above is stateless — each call analyzes the payload you pass, with no memory and no conversation. As of 0.4.0 the sidecar also hosts a session-scoped, conversational agent (/v1/email/agent/*) that runs the full EmailTriageAgent — memory, personalization, and every agent tool — over HTTP, streaming each turn back as Server-Sent Events. Create a session, POST /v1/email/agent/query to run a turn, approve gated tools via /confirm-tool, and toggle memory at runtime via /memory. This is the surface the Agent UI uses; it is not wrapped by the typed client yet — drive it with fetch. See SPEC.md and SKILL.md for the endpoint table and a streaming example.

Running in production

This is a long-lived local resource, not a per-request one. Wire it like this:

Fetch at build time, not per request. fetchBinary does network I/O and SHA-256 verification — run it once in your build / postinstall step, ship the verified binary, then resolveBinaryPath at runtime.
Spawn once at boot. Call startSidecar during app startup and hold the Sidecar handle for the process lifetime. Never spawn per request.
Keep concurrency low. The sidecar accepts concurrent HTTP requests, but inference runs on a single local Lemonade model slot — parallel triage calls queue behind one another. Cap inflight calls (a small queue / concurrency limit) rather than fanning out.
Pick a port you own. port is yours to choose; if it's already taken, startSidecar fails its health wait (HealthTimeoutError) — run with DEBUG=agent-email to see the bind error.
Supervise it yourself. The package does not restart a crashed sidecar. If you need resilience, watch sidecar.child for exit and re-startSidecar.
Cleanup is automatic. By default the sidecar is reaped when your process goes away — normal exit, process.exit(), an uncaught exception, or SIGINT/SIGTERM/SIGHUP (Ctrl+C) — so the frozen binary's detached child never leaks and never keeps holding its port. No signal wiring required. For a graceful, awaited shutdown that lets in-flight work finish, call shutdown(sidecar) (the automatic reaper is a SIGKILL backstop on top of it):

const sidecar = await startSidecar({ binaryPath, port: 8131 });
// … use sidecar.client …
await shutdown(sidecar); // optional & graceful; auto-cleanup also runs on exit

To own the lifecycle yourself, pass autoCleanup: false and wire the signals. (A hard SIGKILL of your process can't be intercepted by anyone, so the safest guarantee is the default in-process reaper.)

const sidecar = await startSidecar({ binaryPath, port: 8131, autoCleanup: false });
const reap = (code = 0) => shutdown(sidecar).finally(() => process.exit(code));
for (const sig of ["SIGTERM", "SIGINT"]) process.once(sig, () => reap(0));

Errors & retries

Every non-2xx throws HttpError (status, url, bodyText); a network failure or timeout surfaces as HttpError with status === 0 (not an HTTP code).

Failure	Meaning	Retry?
`HttpError` 502 (from `triage`)	Lemonade is down or the model is cold/missing	Yes — transient; back off and retry
`HttpError` 0 (network/timeout)	Sidecar not reachable / crashed	Yes — after re-spawning the sidecar
`HttpError` 403 (from `send` / `archive` / `quarantine`)	Missing/invalid confirmation token	No — call `draft` (for `send`) or `confirmAction` (for `archive`/`quarantine`) first and pass its token
`HttpError` 503 (from `send` / `archive` / `quarantine`)	No mailbox connected on the host	No — configuration, not transient
`HttpError` 409 (from `unarchive` / `unquarantine`)	Undo window expired or handle unknown	No — past the 30s window; restore manually in the mail client
`HttpError` 400	Bad request, 2+ mailboxes connected without a provider, or `quarantine` with `is_phishing: false`	No — fix the call/config
`HealthTimeoutError` / `VersionMismatchError` / `IntegrityError`	Startup faults (port taken, contract mismatch, bad binary)	No — fail fast at boot

Playground

One command fetches the binary, starts the sidecar, and opens the playground:

npx @amd-gaia/agent-email playground

It serves a zero-setup, localhost-only page at http://127.0.0.1:8131/v1/email/playground — a stack-health check, live triage and draft, and a Connectors panel to connect Gmail/Outlook and try a live send. It's served same-origin under a strict CSP, so the page can only ever reach your local sidecar: triage and draft stay on-device, while a send transmits to your mail provider by definition. Press Ctrl+C to stop (--port <n> to bind elsewhere, --no-open to skip auto-opening the browser, --out <dir> to choose where the binary is cached).

Requirements

Platforms: Windows x64, Linux x64, macOS Apple Silicon (darwin-arm64).
Memory: 8 GB RAM — sized for the default local model (Gemma-4-E4B-it-GGUF) running in Lemonade, not the sidecar itself.
Lemonade: the sidecar calls a local Lemonade endpoint (default http://localhost:13305); cloud hosts are rejected at startup.
Footprint: one self-contained native binary (~30–45 MB depending on platform), no Python runtime. (Model weights are downloaded and managed separately by Lemonade.)

Troubleshooting

Symptom	Cause & fix
`triage()` returns HTTP 502	Lemonade isn't running or the model isn't pulled. Start it (`lemonade-server serve`) and provision the model (`gaia init`). Not a bug in this package.
`/health` is green but `triage` fails	`health()` is liveness-only — it doesn't check Lemonade or the model. Use `GET /v1/email/init` for real readiness (it probes Lemonade + the model; `503` + `hint` when not ready).
`npm install` fails with `UNABLE_TO_GET_ISSUER_CERT`	Corporate TLS proxy. Reinstall with Node's system CA store: `NODE_OPTIONS=--use-system-ca npm install` (Node ≥ 22).
`require(...)` throws `ERR_REQUIRE_ESM`	The package is ESM-only. Use `import`, or `await import("@amd-gaia/agent-email")` from CommonJS.
Sidecar process lingers after exit	Auto-cleanup reaps it on exit/crash/signal by default; a lingering sidecar means `autoCleanup: false` (call `shutdown(sidecar)` yourself) or a hard `SIGKILL` of the host.
`IntegrityError` / `VersionMismatchError` on start	The downloaded binary failed its SHA-256 check, or its contract MAJOR differs from the client. Clear `resources/` and re-`fetchBinary`, and make sure the package version matches the binary.

Set DEBUG=agent-email for verbose spawn/fetch/health logs (on stderr).

Reference

SPEC.md — full API, lifecycle helpers, connectors, module format, and platforms.
CAPABILITY_MATRIX.md — code-derived, CI-guarded inventory of every capability surface (internal tools, REST, MCP, eval coverage).
SKILL.md — load into Claude Code (or similar) for a step-by-step integration playbook.
SCORECARD.md — latest eval results (score, metrics, per-category breakdown, run environment).
EVALUATION.md — evaluation guide: what's measured, the dataset, a worked example, and how to reproduce the scorecard.
CHANGELOG.md — version history.

License

SPDX-License-Identifier: MIT

@amd-gaia/agent-email — Technical reference

Detailed reference for @amd-gaia/agent-email. For a quick start, see README.md; for an AI-assisted integration walkthrough, see SKILL.md. The contract version is SCHEMA_VERSION 2.3.

Architecture

Three tiers, all on the user's machine:

Your app (a Node process) depends on this package, fetches the sidecar binary, and spawns it via the . entry. It does not attach to an already-running GAIA instance — the package launches and owns its own sidecar and tears it down on shutdown().
The sidecar is a self-contained, PyInstaller-frozen email-agent binary serving the email REST endpoints. No Python is required on the host.
Lemonade Server is the one external runtime dependency: the sidecar calls a local Lemonade for the actual LLM inference. With none reachable, POST /v1/email/triage returns HTTP 502.

Once a sidecar is running, any Node process can drive it over local HTTP. The sidecar serves same-origin only and sends no CORS headers, so a browser or Electron renderer reaches it through the app's main process, not a direct cross-origin fetch — see Browser / Electron renderer.

Concurrency & deployment

Run one sidecar per host, spawned once at process start — not one per request. It accepts concurrent HTTP requests, but inference runs on a single local Lemonade model slot, so parallel triage calls serialize behind one another; cap inflight calls on your side rather than fanning out. The package does not supervise or restart a crashed sidecar — watch sidecar.child exit and re-startSidecar if you need resilience. It does auto-reap the sidecar when your process exits, crashes, or is interrupted (default autoCleanup); call shutdown for a graceful, awaited stop, or pass autoCleanup: false to manage signals yourself.

Authentication

The sidecar binds 127.0.0.1 and can send mail as the user, so it authenticates its caller (#1706) — distinct from the draft→send confirmation_token, which binds a send to one exact message but does not identify the caller.

Per-session bearer token. spawnSidecar / startSidecar mint a cryptographically-random token, pass it to the sidecar over the private GAIA_EMAIL_SIDECAR_TOKEN env channel, and bind it to sidecar.client. Every /v1/email/* request must carry Authorization: Bearer <token> → otherwise 401. Construct-your-own clients pass authToken (from sidecar.authToken); generateSessionToken() is exported for advanced flows. Exempt: /health, /version, /v1/email/health, /v1/email/version, /v1/email/spec, /v1/email/playground.
Host allowlist — non-loopback Host → 400 (DNS-rebinding).
Origin rejection — non-loopback browser Origin → 403 (drive-by page). Non-browser clients send no Origin and are unaffected. No CORS is ever sent.

Running the sidecar by hand without GAIA_EMAIL_SIDECAR_TOKEN disables the token check (local development only, logged loudly); the Host/Origin controls still apply. The shipped product always spawns with a token.

REST API

The code-derived, CI-guarded inventory of every capability surface (internal agent-loop tools, REST, MCP, eval coverage) is CAPABILITY_MATRIX.md — the canonical cross-surface reference.

Every /v1/email/* request also requires the per-session bearer token (see Authentication); the "Auth" column below covers the additional per-endpoint connector/token requirements. EmailClient is a typed wrapper over the sidecar's HTTP surface. Methods: triage, triageBatch, search, prescan, draft, send, confirmAction, archive, unarchive, quarantine, unquarantine, listCalendarEvents, previewCalendarEvent, createCalendarEvent, respondToCalendarEvent, health, version, emailHealth, emailVersion, spec, openapi. health/version hit the root routes (the standalone sidecar); emailHealth/emailVersion hit the /v1/email-scoped mirrors (for when the router is mounted on a product app). Every non-2xx response throws HttpError (carrying status, url, bodyText) — never a silent empty/null result.

Endpoint	Client method	Auth	What it needs
`POST /v1/email/triage`	`triage()`	Standalone	Local Lemonade LLM only. Categorizes / summarizes / extracts action items + spam/phishing signals on the message you send in. No mailbox is read. Extracted action items also persist to the sidecar's local task list (see "Action-item task persistence" below); the response shape is unchanged.
`POST /v1/email/triage/batch`	`triageBatch()`	Standalone	Same as `triage` for an `items` array (1–100). Returns a parallel `results` array, order-preserved; per-item failures isolate (HTTP 200 can carry errored items — inspect `results[].error`). A `502` fails the whole batch (Lemonade unreachable).
`POST /v1/email/search`	`search()`	Connector	Read-only inbox search. A connected Google/Microsoft mailbox (`503` if none, `400` if 2+); no confirmation token. Lists messages matching `query`/`labels` and returns metadata only (no body).
`POST /v1/email/prescan`	`prescan()`	Connector	Reads recent inbox messages from the connected Google/Microsoft mailbox and returns the read-only triage-card envelope (`kind: "email_pre_scan"`). `503` if no mailbox is connected, `400` if 2+ are. Heuristic-only — no Lemonade call.
`GET /v1/email/briefing`	— (plain `fetch`; no wrapper yet)	Standalone	The latest scheduled daily briefing (#1608) — the same `email_pre_scan` envelope as `prescan`, generated by the sidecar's daily timer without a prompt, plus a `generated_at` stamp. Off by default: start the sidecar with `GAIA_EMAIL_BRIEFING_ENABLED=true` (fire time `GAIA_EMAIL_BRIEFING_TIME`, 24h local `HH:MM`, default `08:00`; scan size `GAIA_EMAIL_BRIEFING_MAX_MESSAGES`, default 25) — e.g. via `startSidecar({ env: {...} })`. `404` until a scheduled run has happened.
`POST /v1/email/draft`	`draft()`	Standalone	Nothing external — wraps your `(to, subject, body, attachments)` and returns a single-use confirmation token.
`POST /v1/email/send`	`send()`	Connector	A valid `draft` confirmation token and a connected Google/Microsoft mailbox. The token gate fires first: no/invalid token → `403`; then `503` if no mailbox is connected, `400` if 2+ are.
`POST /v1/email/confirm`	`confirmAction()`	Standalone	Nothing external — mints a single-use token for `"archive"`/`"quarantine"`, bound to that exact `(action, message_id)`.
`POST /v1/email/archive`	`archive()`	Connector	A valid `confirm` token (`action="archive"`) and a connected mailbox. Gate fires first (no/invalid token → `403`); returns a `batch_id` undo handle + `post_archive_id`.
`POST /v1/email/unarchive`	`unarchive()`	Connector	A connected mailbox + the `batch_id`. Ungated (it restores). Window expired / unknown handle → `409`.
`POST /v1/email/quarantine`	`quarantine()`	Connector (Gmail)	A valid `confirm` token (`action="quarantine"`) and a connected Gmail mailbox. Applies `GAIA_PHISHING_QUARANTINE` + archives; refuses `is_phishing: false` → `400`; refuses an Outlook mailbox → `400` (label-undo can't reverse a folder move, #1738).
`POST /v1/email/unquarantine`	`unquarantine()`	Connector	A connected mailbox + the `action_id`. Ungated (it restores prior labels). Window expired / unknown → `409`.
`GET /v1/email/calendar/events`	`listCalendarEvents()`	Connector	A connected mailbox whose calendar scope was granted. Read-only view of the primary calendar; `403` (reconnect CTA) if the scope is missing. Optional `time_min`/`time_max`; `provider` only when 2+ accounts.
`POST /v1/email/calendar/events/preview`	`previewCalendarEvent()`	Standalone	Nothing external — mints a single-use confirmation token bound to the event (calendar analogue of `draft`).
`POST /v1/email/calendar/events`	`createCalendarEvent()`	Connector	A valid `preview` token and a connected calendar. Token gate fires first: no/invalid token → `403`; then the calendar-scope / account checks.
`POST /v1/email/calendar/events/respond`	`respondToCalendarEvent()`	Connector	A connected calendar. RSVPs `accepted`/`declined`/`tentative` to an existing invite.
`GET /v1/email/init`	`init()`	Standalone	Readiness preflight (#1795): probes the whole triage stack — Lemonade reachable and version-compatible and the triage model downloaded. Returns `200` when ready, `503` when not, with an actionable `hint` either way (same `InitResponse` envelope). Read-only — no model pull. Unlike `/health` (liveness only), this verifies "ready to triage," not just "process up."
`POST /v1/email/init`	— (streaming; no wrapper yet)	Standalone	Provisioning (#1795): tells the running local Lemonade to download the configured triage model, streaming `text/plain` progress line-by-line. Lemonade unreachable → real `503` (pulls nothing); once a pull starts the `200` is committed, so the trailing `✓`/`✗` line carries the true outcome. Not in the OpenAPI JSON — a streaming operational verb (like `GET /spec`), so `include_in_schema=False`.
`GET /health`	`health()`	Standalone	Liveness only — does not check Lemonade/model.
`GET /version`	`version()`	Standalone	Version negotiation.
`GET /v1/email/health`	`emailHealth()`	Standalone	Router-scoped liveness (mounted-on-app case).
`GET /v1/email/version`	`emailVersion()`	Standalone	Router-scoped version.
`GET /v1/email/spec`	`spec()`	Standalone	Human-readable HTML endpoint page.
`GET /openapi.json`	`openapi()`	Standalone	Machine-readable OpenAPI document.

GET /docs (Swagger UI) and GET /redoc are also served but are browser UIs, not wrapped by the client. The standalone surface is triage, draft, confirmAction, and previewCalendarEvent (plus the probes) — integrate and verify those flows with zero connector setup. The read-only search and prescan read the live inbox (a connected mailbox, but no token); the mutating calls (send, archive, quarantine, createCalendarEvent) and the reversals/calendar views need a connected mailbox whose relevant scope was granted.

Stateful agent surface (`/v1/email/agent/*`, 0.4.0)

Everything above is stateless — each call analyzes the payload you send, with no memory and no agent loop. The sidecar also hosts a session-scoped, conversational agent so a host can drive the full EmailTriageAgent (memory, personalization, and every agent tool) over HTTP instead of importing it in-process. This is the surface the Agent UI uses to back its email experience with the packaged sidecar. It is not wrapped by the typed npm client yet — call it directly (e.g. fetch) or via the Agent UI.

Endpoint	Notes
`POST /v1/email/agent/session`	Create/reset a session (`{ session_id, reset? }`) → `{ created, memory }`. Builds the agent (surfaces failures early).
`POST /v1/email/agent/query`	Run one turn; SSE stream (`text/event-stream`) of the loop — `thinking`/`step`/tool/`permission_request`/`error`/terminal `run_complete`. Body `{ session_id, message, memory_enabled? }`. Every agent tool is reachable via natural language. Overlapping turn → 409.
`POST /v1/email/agent/confirm-tool`	Approve/deny a gated tool the run is blocking on (`{ session_id, approved }`).
`POST /v1/email/agent/cancel`	Cooperatively cancel the in-flight run.
`DELETE /v1/email/agent/session/{id}`	Evict a session + tear down its agent.
`GET /v1/email/agent/session/{id}/history`	Conversation so far (`turns[]`, oldest first).
`POST /v1/email/agent/memory`	Runtime memory toggle (#1666), `{ session_id, enabled }` → `{ enabled, available, message }`. Enabling memory that was never initialized (started with `GAIA_MEMORY_DISABLED` / Lemonade unreachable) → 409, never a silent no-op.
`GET /v1/email/agent/memory/{id}`	Memory status without changing it.

Sessions are in-process and single-tenant (the sidecar hosts one user's agent); one turn runs at a time per session. Memory uses FAISS locally; embeddings still go over Lemonade HTTP, so the frozen binary stays free of torch/transformers.

Mailbox actions (archive / quarantine, schema 2.1)

archive and quarantine mutate the live mailbox, so each is gated on a single-use token exactly like send — but minted by confirmAction (not draft), bound to the (action, message_id). A token for one action/message cannot authorize a different one. Both are reversible inside the 30s undo window:

// Archive (gated) → undo within the window (ungated):
const { confirmation_token } = await client.confirmAction({
  action: "archive",
  message_id: "msg-123",
});
const { batch_id, post_archive_id } = await client.archive({
  message_id: "msg-123",
  confirmation_token,
});
// post_archive_id is the id valid NOW — Outlook mints a new one on the folder move.
await client.unarchive({ batch_id }); // restores to inbox; 409 if the window lapsed

// Quarantine a phishing message (Gmail-only; refuses is_phishing:false and Outlook), then undo by action_id:
const t = await client.confirmAction({ action: "quarantine", message_id: "msg-9" });
const q = await client.quarantine({
  message_id: "msg-9",
  is_phishing: true,
  confirmation_token: t.confirmation_token,
});
await client.unquarantine({ action_id: q.action_id });

Calendar (view / create / respond, schema 2.1)

Confirmation gating — deliberate asymmetry. send and calendar create are token-gated (a payload-bound confirmation_token from draft / previewCalendarEvent; no/invalid token → 403). Calendar respond (RSVP) is intentionally not token-gated, even though the in-process agent treats accept_invite / decline_invite as confirmation-tier tools. The contract draws the line at irreversibility: send and create are externally visible and not cleanly undoable, whereas an RSVP only sets your own response status on an existing invite and can be changed by responding again. The REST caller (the Agent UI's accept/decline controls) is the human-in-the-loop for that reversible action.

Agent-loop capabilities not on the contract

Some agent capabilities run only in the agent tool loop (chat / Agent UI / gaia email) and have no REST endpoint, so this package's EmailClient can't drive them — they reach hosts through the agent chat surface until routes land in a future schema bump:

Scheduled send + snooze (#1609): schedule_send, snooze_message, cancel_scheduled_job, list_scheduled_jobs. A send is user-confirmed at creation, persisted as a mailbox draft plus a one-shot job in the agent's SQLite, and fired by the agent's scheduler at/after its time.
Voice / style-matched drafting (#1607): build_voice_profile samples the user's Sent mail into a local style profile (top greetings / sign-offs, typical length, contraction & exclamation rate — derived features only, never raw content, stored on-device), and the agent's system prompt injects that guidance every turn so drafted reply bodies come out in the user's own voice instead of a neutral scaffold; clear_voice_profile forgets it. Read-only over Sent mail — nothing remote is mutated.
Follow-up tracking (#1606): check_followups scans every connected mailbox's Sent folder and flags threads whose latest message is still the user's own outbound mail past a configurable window (default 3 days), most overdue first. Detection only — it never sends a nudge (any send stays confirmation-gated).

None of these are on the REST/MCP contract, so none of them moves SCHEMA_VERSION.

Readiness vs liveness

health() is liveness-only — a green /health means "the REST surface is up," not "triage will work." On a fresh machine the binary boots fine, but the first triage returns HTTP 502 until a local Lemonade Server is running and the configured model is pulled.

The authoritative readiness signal is GET /v1/email/init (#1795): it probes the whole triage stack — Lemonade reachable and version-compatible and the triage model downloaded — and returns 200 when ready, 503 when not, with an actionable hint. The init() client method wraps it — returning the InitResponse on both the ready (200) and not-ready (503) paths (branch on .ready), and, like every EmailClient method, attaching the per-session bearer token (#1706) for you. A raw fetch works too (the InitResponse type is exported) but must attach it:

const r = await fetch("http://127.0.0.1:8131/v1/email/init", {
  headers: { Authorization: `Bearer ${sidecar.authToken}` },
});
const init = (await r.json()) as import("@amd-gaia/agent-email").InitResponse;
if (!init.ready) throw new Error(init.hint ?? "email agent not ready to triage");

POST /v1/email/init is the companion provisioning verb: it asks the running Lemonade to pull the model and streams text/plain progress. It cannot install Lemonade itself (a host prerequisite) — if Lemonade is unreachable it returns 503 and pulls nothing.

Request shapes

Recipients and senders are address objects, not bare strings: { email: string, name?: string }. This applies to triage's message.from and principal, and to draft/send's to (a non-empty array of them). Passing a plain string for to is a 422 validation error.

draft proposes a reply and mints a single-use confirmation_token bound to that exact message; send echoes it back. A full round-trip:

const { draft, confirmation_token } = await client.draft({
  to: [{ email: "you@example.com" }],
  subject: "Re: Prod incident",
  body: "On it — fix lands today.",
});
// `draft` is { to, subject, body, attachments }; the token authorizes exactly
// this payload.
const sent = await client.send({ ...draft, confirmation_token });
console.log(sent.sent_id);

Attachments (schema 2.2, #1542)

draft and send accept an optional attachments array of { filename, mime_type, content_base64 } (standard base64, ≤ 25 MB decoded each). Validation is fail-loud (422 for bad base64, a malformed MIME type, an empty file, or oversize — never a silent drop), and the confirmation token binds to each attachment's filename, MIME type, and content digest: a send whose attachment set differs in any way from the confirmed draft is rejected with 403. Note the send payload carries the full content_base64 — spread the request you drafted with, not the metadata-only draft echo, when attaching files:

const req = {
  to: [{ email: "you@example.com" }],
  subject: "Re: Prod incident",
  body: "Report attached.",
  attachments: [{
    filename: "incident-report.pdf",
    mime_type: "application/pdf",
    content_base64: reportB64,
  }],
};
const { confirmation_token } = await client.draft(req);
const sent = await client.send({ ...req, confirmation_token });
// sent.attachments echoes [{ filename, mime_type, size_bytes }] — metadata only.

Outlook mailboxes cap each attachment at 3 MB (the Graph simple-attach limit) — a larger file fails the send loudly rather than being truncated.

Triage response shape

triage returns { schema_version, request_kind, result }. The result (EmailTriageResult) is what you route on:

Field	Type	Notes
`category`	`"URGENT" \| "NEEDS_RESPONSE" \| "FYI" \| "PROMOTIONAL" \| "PERSONAL"`	The five buckets — uppercase wire strings (`res.result.category === "URGENT"`).
`is_spam`, `is_phishing`	`boolean`	Independent signals (a message can be neither, either, or both).
`summary`	`string`	Plain-text summary of the message/thread.
`action_items`	`ActionItem[]`	Each `{ description, due_hint?, type?: "text" \| "link", url? }`; may be empty.
`suggested_action`	`"reply" \| "none" \| "archive"`	`"reply"` for URGENT/NEEDS_RESPONSE, `"archive"` for PROMOTIONAL, else `"none"`.
`draft`	`DraftScaffold \| null`	A proposed reply scaffold (`{ to, subject }` — no body) when one is suggested (schema 2.3). Triage never composes reply prose; compose the body yourself and call `draft()` for a full `DraftReply` + confirmation token.
`usage`	`TriageUsage \| null`	LLM token/latency metrics; `null` on the heuristic-only path.
`attachments`	`AttachmentMeta[]`	Metadata (`{ filename, mime_type, size_bytes, attachment_id? }`) of the analyzed message's attachments, echoed from the request for downstream processing (schema 2.2; empty when none).

The full request/response types are exported from the package (src/types.ts) for exact field-level reference.

Action-item task persistence (additive, #1605)

Beyond returning action_items inline, triage / triageBatch persist each extracted item as a task row in the sidecar's local SQLite (~/.gaia/email/state.db), linked back to the source via the request's message_id (or thread_id for a thread). Persistence is de-duplicated per message on the normalized description, so re-triaging the same message never creates duplicate tasks. Results with no message_id are not persisted (no source to link back to). This is a side-effect only — the wire response is byte-for-byte what it was before; there is no read/complete task endpoint on this contract yet (that surface arrives with GAIA's cross-agent task store, amd/gaia#1521).

Batch triage shape (additive, #1887)

triageBatch takes { schema_version?, items, context? } where items is 1–100 EmailInput objects (the same SingleEmailInput / ThreadInput shapes triage accepts, discriminated on kind), and context — when present — applies to all items. It returns { schema_version, results } with one BatchItemResult per item, order-preserved (1:1 with items):

Field	Type	Notes
`index`	`number`	0-based position in the request `items` array.
`result`	`EmailTriageResult \| null`	Set when the item succeeded (same shape as `triage`'s `result`).
`error`	`BatchItemError \| null`	Set (with a `message`) when the item failed. Exactly one of `result` / `error` is set.

HTTP 200 with every item errored is a valid response — a per-item failure does not fail the request, so always inspect each results[].error, never just the HTTP status. A 502 means Lemonade was unreachable before any item ran (the whole batch fails). The single triage() endpoint and its types are unchanged; MAX_BATCH_SIZE is exported for the 100-item cap (over-cap → 422).

Inbox search shape

search({ query?, labels?, max_results? }) lists messages from the connected mailbox and returns { schema_version, query, count, messages, next_page_token }. It is read-only — no body is read in full, nothing is modified, no confirmation token is involved. Both query and labels are optional: a query searches all mail (Gmail search semantics), labels filter to those labels, and with neither it lists the INBOX. max_results is 1–100 (default 25); each match is hydrated with a per-message fetch, so the cap bounds that fan-out. To page, pass the response's next_page_token back as the request's page_token. Each messages[] item:

Field	Type	Notes
`id`	`string`	Provider message id (opaque) — pass to the agent/triage path to read in full.
`thread_id`	`string \| null`	Provider thread id.
`subject`	`string`	Subject line.
`from`	`string`	Raw `From` header (e.g. `"Sarah Chen <sarah@example.com>"`) — a string, not an address object, unlike triage's `from`.
`to`	`string`	Raw `To` header.
`date`	`string`	Raw `Date` header.
`snippet`	`string`	Provider-supplied short preview.
`label_ids`	`string[]`	Label ids on the message.

const { messages } = await client.search({ query: "is:unread", max_results: 20 });
for (const m of messages) console.log(m.subject, "—", m.from);

Lifecycle helpers

startSidecar(opts) does spawn → waitForHealth → checkVersion in one call and shuts down on any failure so a failed start never leaks a process. For finer control, the steps are exported individually:

fetchBinary(opts) → download + verify + install; returns { binaryPath, sha256, cached, ... }.
resolveBinaryPath({ resourcesDir }) → locate a fetched binary (throws BinaryNotFoundError if absent).
spawnSidecar({ binaryPath, host?, port?, extraArgs? }) → spawn with --host 127.0.0.1 --port <p> (default port 8131).
waitForHealth(baseUrl, { timeoutMs }) → poll /health; throws HealthTimeoutError on timeout (never assumes ready).
checkVersion(client, { expectedApiVersion }) → throws VersionMismatchError if the sidecar's apiVersion MAJOR differs (a higher MINOR is accepted).
verifySha256(buf, expected, label) → throws IntegrityError on mismatch.
shutdown(sidecar) → kill the whole process tree (taskkill /F /T on Windows; detached process-group kill on POSIX). The default auto-reaper does the same on process exit/crash/signal, so only a hard SIGKILL of the host can still orphan the child.

CLI

npx @amd-gaia/agent-email playground          # fetch + run the sidecar, open the playground
npx @amd-gaia/agent-email fetch --out resources
npx @amd-gaia/agent-email version             # show manifest + current platform
npx @amd-gaia/agent-email help

playground is the zero-to-running shortcut: it fetchBinarys into a temp cache (--out to override), startSidecars on --port (default 8131), opens the default browser to /v1/email/playground (--no-open to skip), and runs until Ctrl+C. The command owns the sidecar lifecycle itself (autoCleanup: false) and shuts it down on SIGINT/SIGTERM/SIGHUP or on any startup error. Lemonade still has to be running for live triage — the page itself reports if it isn't.

fetch is the supported, build-time path. It resolves ${process.platform}-${process.arch}, downloads that platform's artifact from the base URL in binaries.lock.json, verifies its SHA-256 against the lock and fails loudly on any mismatch, writes it to --out, and chmod +x's it on POSIX.

Flag	Meaning
`--out <dir>`	Resources dir to write the verified binary into (required)
`--base-url <url>`	Override the download base URL (defaults to the lock's `baseUrl`)
`--platform <key>`	Override platform key (e.g. `linux-x64`); default is the host
`--force`	Re-download even if a verified binary already exists

SHA-256 is mandatory. There is no "use it anyway" path — a corrupt, truncated, or tampered download is rejected before it can ever be spawned, and the bad file is not left on disk.

Connectors & auth

An endpoint that works on the content you pass in the request is standalone — it needs nothing but the local Lemonade LLM. An action that reads from or acts on the live Gmail/Outlook mailbox or calendar requires the Google or Microsoft connector (OAuth), configured in GAIA under Settings → Connectors.

send resolves its OAuth token from the local GAIA connector store (gaia.connectors) on the host — EmailSendRequest has no access_token field (provider is only a routing hint). There is no way to pass or forward a connection through this package's API, so connector-backed calls only work on a machine where the mailbox is already connected in GAIA. Triage and draft, which need no connector, work anywhere.

As of SCHEMA_VERSION 2.2 this package's REST API exposes the read-only inbox search and pre-scan (search / prescan), the archive and phishing-quarantine mailbox actions plus their undo (confirmAction / archive / unarchive / quarantine / unquarantine), calendar view / create / respond (listCalendarEvents / previewCalendarEvent / createCalendarEvent / respondToCalendarEvent), and attachments on triage/draft/send (#1542). The full GAIA email agent does more on the live mailbox (label, move, mark spam) and calendar (detect / conflicts); those remaining actions are connector-gated by definition and are not exposed through this package's REST API yet.

Browser / Electron renderer (`./client`)

The default entry (.) pulls in Node built-ins (node:fs, node:child_process, node:crypto) to fetch and spawn the binary, so it can't be bundled for a browser or an Electron renderer. The browser-safe ./client subpath re-exports only zero-Node-dependency symbols — EmailClient, every error class, SCHEMA_VERSION, and all request/response types — so it bundles for a renderer.

But the sidecar serves same-origin only and sends no CORS headers, so a renderer on a different origin cannot fetch http://127.0.0.1:8131 directly. Two working patterns:

Electron (recommended): spawn and own the sidecar in your main process (the . entry), and expose triage/draft to the renderer over your own IPC.
Same-origin / proxied: use ./client from a page that already shares the sidecar's origin, or behind a proxy you control.

import { EmailClient } from "@amd-gaia/agent-email/client";

// Same-origin or proxied path only — not a cross-origin fetch at 127.0.0.1:8131.
const client = new EmailClient({ baseUrl: "http://127.0.0.1:8131" });
const res = await client.triage({ payload: { /* … */ } });

Module format

The package is ESM-only ("type": "module"; no CommonJS build). Import it with import …. From a CommonJS module, use a dynamic import instead of require:

const { startSidecar } = await import("@amd-gaia/agent-email");

Plain JavaScript works — the package ships compiled JS in dist/; TypeScript is the authoring language, not a consumer requirement. The bundled .d.ts files give editors autocomplete but your code never imports them.

Types

TypeScript types in src/types.ts mirror two Python sources of truth:

contract.py — the triage request/response contract plus the schema-2.1 additions (inbox search, mailbox actions, calendar, pre-scan), the schema-2.2 attachment models (AttachmentMeta / OutgoingAttachment), and the schema-2.3 triage draft scaffold (DraftScaffold; SCHEMA_VERSION = "2.3").
api_routes.py — the local draft/send confirmation handshake models, the readiness-preflight envelope (InitResponse / InitLemonadeStatus / InitModelStatus, #1795), and the scheduled-briefing response (EmailBriefingResponse, #1608).

They are hand-written (vs. generated from /openapi.json) because the contract is small and version-gated, keeping the published package free of a typegen build step. The runtime checkVersion guard catches contract drift loudly; the server exposes GET /openapi.json if you prefer to regenerate.

Wire note: EmailMessage.from is the JSON key on the wire (Python aliases its from_ field to from), so the TS interface uses from directly.

Platforms

Fully supported: win32-x64, linux-x64, darwin-arm64 (Apple Silicon). Intel macOS (darwin-x64) is a best-effort target — built when the release can, and omitted with a clear "no binary for darwin-x64" install error otherwise. Each binary is built natively (PyInstaller does not cross-compile); binaries.lock.json maps every available platform to its artifact filename, SHA-256, and size.

License

SPDX-License-Identifier: MIT

name: integrate-agent-email description: Use when integrating the @amd-gaia/agent-email npm package — embedding the GAIA email agent (a local triage/draft/send sidecar) into a Node, TypeScript, or Electron app. Covers install, spawning the sidecar, calling the typed client, prerequisites, and the common gotchas.

Integrating @amd-gaia/agent-email

@amd-gaia/agent-email embeds the GAIA email agent in a JS/TS app. It triages, drafts, and sends email locally on AMD Ryzen AI — no cloud LLM. This package is the client: it downloads a frozen native sidecar binary, spawns it, and talks to it over local HTTP. There is no Python and no separate GAIA install.

Follow these steps to wire it into an app.

1. Install

npm install @amd-gaia/agent-email

The package is ESM-only ("type": "module"). Use import, not require. From a CommonJS file, use await import("@amd-gaia/agent-email").

2. Pick the right entry point

Node / main process → the default entry @amd-gaia/agent-email. It can fetch the binary and spawn/own the sidecar (uses node:fs, node:child_process).
Browser / Electron renderer → the @amd-gaia/agent-email/client subpath. It has zero Node built-ins and only talks to an already-running sidecar over HTTP.

The desktop pattern: spawn the sidecar once from the Node/main process, then drive it from the renderer via ./client.

3. Fetch the binary and start the sidecar (Node)

import { fetchBinary, startSidecar, shutdown } from "@amd-gaia/agent-email";

// Build time (or first run): download + SHA-256-verify the platform binary.
const { binaryPath } = await fetchBinary({ outDir: "resources" });

// Runtime: spawn -> wait for /health -> version-check, in one call.
const sidecar = await startSidecar({ binaryPath, port: 8131 });

// ... use sidecar.client ...

await shutdown(sidecar); // graceful stop — auto-cleanup also reaps on exit

fetchBinary writes a verified binary into outDir. SHA-256 is mandatory; a bad download is rejected and not left on disk. Run it at build time or guard it to run once.
startSidecar throws if the binary can't start, never becomes healthy, or the contract MAJOR version mismatches — and cleans up so a failed start leaks nothing.
The sidecar is auto-reaped when your process exits, crashes, or is signalled (default autoCleanup), so a missed shutdown won't orphan the frozen binary's child. shutdown(sidecar) is the graceful, awaited stop; autoCleanup: false opts out.

4. Call the typed client

const res = await sidecar.client.triage({
  payload: {
    kind: "single",
    principal: { email: "me@example.com" },
    message: {
      message_id: "m1",
      from: { name: "Sarah Chen", email: "sarah@example.com" },
      subject: "Prod incident follow-up",
      body: "Please review the report and reply by Friday.",
    },
  },
});
console.log(res.result.category, res.result.summary);

To classify many messages at once, use triageBatch — an items array (1–100) in, a parallel results array out, order-preserved. It's additive (the single triage above is unchanged). Per-item failures isolate, so an HTTP 200 can still carry errored items — inspect each results[].error, never just the status:

const batch = await sidecar.client.triageBatch({
  items: [
    { kind: "single", principal: { email: "me@example.com" },
      message: { message_id: "m1", from: { email: "sarah@example.com" },
        subject: "Prod incident", body: "Reply by Friday." } },
  ],
});
for (const r of batch.results) {
  if (r.error) console.warn(`item ${r.index} failed: ${r.error.message}`);
  else console.log(`item ${r.index}:`, r.result!.category);
}

The interface:

Call	Needs	Notes
`triage(req)`	Local LLM only	Classify / summarize / extract action items + phishing signals on the message you pass. No mailbox read. Action items also persist to the sidecar's local task list (keyed by `message_id`, de-duplicated on re-triage) — the response shape is unchanged.
`triageBatch(req)`	Local LLM only	Same as `triage` for an `items` array (1–100). Parallel `results` array; per-item failures isolate (200 can carry errored items — inspect `results[].error`).
`search(req)`	A connected mailbox	Read-only inbox search by `query`/`labels`; returns message metadata (id, subject, sender, snippet, labels), no body. No token. No mailbox → 503, two+ → 400.
`prescan(req?)`	A connected mailbox	Read-only inbox pre-scan → triage-card envelope (`kind: "email_pre_scan"`: urgent / actionable / suggested-archive rows + an informational count). No mailbox connected → 503; 2+ → 400. Heuristic-only, no Lemonade call.
`draft(req)`	Nothing external	Returns a single-use confirmation token. Optional `attachments` (schema 2.2): `{ filename, mime_type, content_base64 }` each, ≤ 25 MB decoded.
`send(req)`	Draft token + a connected mailbox	Gate fires first: no/invalid `draft` token → 403; valid token but no mailbox connected on the host → 503. Attachments must exactly match the confirmed draft's (the token binds their content digests).
`confirmAction(req)`	Nothing external	Mints a single-use token for `"archive"`/`"quarantine"`, bound to the `(action, message_id)`.
`archive(req)`	`confirm` token + a connected mailbox	Removes from inbox. Gate fires first (no/invalid token → 403). Returns a `batch_id` undo handle (+ `post_archive_id` for the Outlook id change).
`unarchive(req)`	A connected mailbox	Restores within the 30s window (ungated — pass `batch_id`); expired/unknown → 409.
`quarantine(req)`	`confirm` token + a connected Gmail mailbox	Applies `GAIA_PHISHING_QUARANTINE` + archives a phishing message. Refuses `is_phishing:false` → 400; Gmail-only (Outlook → 400).
`unquarantine(req)`	A connected mailbox	Restores prior labels within the 30s window (ungated — pass `action_id`); expired/unknown → 409.
`listCalendarEvents(opts?)`	Connected mailbox + calendar scope	Read-only view of the primary calendar. Optional `timeMin`/`timeMax`; `provider` only when >1 account. Missing scope → 403 + reconnect CTA.
`previewCalendarEvent(req)`	Nothing external	Mints a single-use confirmation token bound to the event (calendar analogue of `draft`).
`createCalendarEvent(req)`	Preview token + connected calendar	Token gate fires first: no/invalid token → 403, then the calendar checks.
`respondToCalendarEvent(req)`	Connected calendar	RSVP `accepted`/`declined`/`tentative` to an existing invite.

Build the standalone surface (triage, draft, confirmAction, previewCalendarEvent) with zero connector setup. The read-only search and prescan read the live inbox (a connected mailbox, no token); send, the mailbox actions (archive / quarantine), and the calendar actions (view / create / respond) need a connected mailbox whose relevant scope was granted. Mint the gate token with draft (for send), confirmAction (for archive / quarantine), or previewCalendarEvent (for createCalendarEvent); archive and quarantine are reversible inside a 30s window via the ungated unarchive / unquarantine. Every non-2xx response throws HttpError (status, url, bodyText) — handle it; there is no silent null.

Scheduled daily briefing (#1608, REST-only): the sidecar can run prescan on a daily timer with no prompt. Off by default — launch with startSidecar({ env: { GAIA_EMAIL_BRIEFING_ENABLED: "true" } }) (fire time GAIA_EMAIL_BRIEFING_TIME, 24h local HH:MM, default 08:00), then pull the latest run from GET /v1/email/briefing with plain fetch (no client wrapper yet). 404 until the first scheduled run; an invalid env value fails sidecar startup loudly.

5. From a renderer (Electron / browser)

The sidecar serves same-origin only — no CORS. A renderer on a different origin cannot fetch http://127.0.0.1:8131 directly; the browser blocks it. So:

Recommended: spawn the sidecar in the Electron main process (step 3) and expose triage/draft to the renderer over your own IPC. Don't call the sidecar from the renderer directly.
The ./client entry (zero Node built-ins) is only usable from a same-origin or proxied page:

import { EmailClient } from "@amd-gaia/agent-email/client";
// Pass the sidecar's session token (from sidecar.authToken in the main process,
// forwarded over IPC) — without it every /v1/email/* call is 401.
const client = new EmailClient({ baseUrl: "http://127.0.0.1:8131", authToken });

Stateful agent surface (`/v1/email/agent/*`, 0.4.0)

Everything above is stateless — you send a payload, the sidecar analyzes it, no memory, no conversation. The sidecar also hosts a session-scoped, conversational agent that runs the full EmailTriageAgent (memory, personalization, every agent tool) over HTTP. This is the surface the Agent UI uses. It is not wrapped by the typed EmailClient yet — call it directly with fetch against the sidecar's baseUrl:

const base = "http://127.0.0.1:8131";
// 1. Start a session (builds the agent; reports memory availability).
await fetch(`${base}/v1/email/agent/session`, {
  method: "POST", headers: { "content-type": "application/json" },
  body: JSON.stringify({ session_id: "s1" }),
});

// 2. Run a turn — the reply streams back as Server-Sent Events.
const res = await fetch(`${base}/v1/email/agent/query`, {
  method: "POST", headers: { "content-type": "application/json", accept: "text/event-stream" },
  body: JSON.stringify({ session_id: "s1", message: "Triage my inbox" }),
});
const reader = res.body.getReader(); const dec = new TextDecoder(); let buf = "";
for (;;) {
  const { value, done } = await reader.read(); if (done) break;
  buf += dec.decode(value, { stream: true });
  let i; while ((i = buf.indexOf("\n\n")) >= 0) {
    const line = buf.slice(0, i).split("\n").find(l => l.startsWith("data: "));
    buf = buf.slice(i + 2);
    if (!line) continue;
    const ev = JSON.parse(line.slice(6));           // {type: "thinking"|"step"|"permission_request"|"run_complete"|...}
    if (ev.type === "permission_request") {         // a gated tool (send/forward/delete/...) is waiting
      await fetch(`${base}/v1/email/agent/confirm-tool`, {
        method: "POST", headers: { "content-type": "application/json" },
        body: JSON.stringify({ session_id: "s1", approved: true }),
      });
    }
    if (ev.type === "run_complete") console.log("answer:", ev.answer);
  }
}

Other endpoints: POST /cancel, DELETE /session/{id}, GET /session/{id}/history, and the runtime memory toggle POST /memory + GET /memory/{id} (enabling memory that was never initialized returns 409, never a silent no-op). One turn at a time per session — an overlapping /query returns 409. See SPEC.md for the full table.

Running in a server / long-lived app

fetchBinary is a build step, not per request (network + SHA verify). Run it once; resolveBinaryPath at runtime.
Spawn once at boot, hold the Sidecar handle for the process lifetime — never per request.
Low concurrency. One local Lemonade model slot, so parallel triage calls serialize. Cap inflight calls.
Cleanup is automatic (default autoCleanup): the sidecar's child is reaped on exit/crash/signal. Call shutdown for a graceful stop, or autoCleanup: false to wire signals yourself. The package does not restart a crashed sidecar.

Prerequisites — the agent needs a local model

The sidecar runs the LLM via Lemonade Server, which this package does not install. Before triage/draft/send succeed, the host must have:

A running Lemonade Server (lemonade-server serve).
The model pulled (gaia init installs Lemonade and downloads the default model).

Until then the binary boots, but the first triage returns HTTP 502.

Gotchas (read before debugging)

Every /v1/email/* call needs the session token (#1706). sidecar.client carries it automatically; a client you construct yourself must pass authToken (from sidecar.authToken) or every call is 401. Non-loopback Host → 400, non-loopback browser Origin → 403. /health · /version · /v1/email/spec · /v1/email/playground are exempt.
health() is liveness-only. A green /health means the REST surface is up, NOT that triage will work. For real readiness call init() (GET /v1/email/init, #1795) — it probes Lemonade + the triage model and returns the InitResponse on both the ready (200) and not-ready (503) paths, so branch on .ready / read .hint. POST /v1/email/init streams a model-pull (no wrapper yet).
HTTP 502 from triage → Lemonade isn't running/reachable, or the model isn't pulled. It is not a bug in this package.
Addresses are objects, not strings. to (and triage's from / principal) are { email, name? }; to is a non-empty array of them. A plain string → 422.
send needs the draft confirmation_token (missing/invalid → 403), but it takes no OAuth token — the mailbox is resolved from the host's GAIA connector store (no mailbox connected → 503). The read-only search / prescan resolve the mailbox the same way (503 with none, 400 with 2+). Triage and draft need no connector.
Attachments bind to the token (schema 2.2). Re-send the exact attachments array you drafted with — the metadata-only draft echo has no content_base64, so spreading the echo into send loses the files. A swapped/extra/missing attachment → 403; bad base64, a malformed MIME type, or > 25 MB decoded → 422; Outlook additionally rejects files over 3 MB (Graph simple-attach limit).
archive / quarantine are gated like send, but their token comes from confirmAction (not draft) and is bound to the (action, message_id) — a token for one can't authorize the other. Undo with unarchive (pass the returned batch_id) / unquarantine (pass the action_id) within 30s; past the window the reversal returns 409 (restore manually in the mail client). For Outlook, use the post_archive_id from the archive response — the folder move changes the id.
Cleanup is automatic by default — the sidecar is reaped on exit/crash/signal; only autoCleanup: false (or a hard SIGKILL of your process) can orphan the child. shutdown stays the graceful stop.
Some capabilities are agent-loop-only — no REST endpoint, no client method. Scheduled send / snooze (#1609), voice / style-matched drafting (#1607 — build_voice_profile learns a local style profile from Sent mail so drafts come out in the user's own voice), and follow-up tracking (#1606 — check_followups flags sent mail still awaiting a reply, detection only) all run in the agent tool loop. The REST contract has no routes for them yet, so don't look for client.scheduleSend() / client.snooze() / a voice or follow-up method — they don't exist (and none of these moves SCHEMA_VERSION).
ESM-only. require("@amd-gaia/agent-email") fails; use import / dynamic import().

Verify the integration

A green path looks like: fetchBinary succeeds → startSidecar resolves → client.triage(...) returns a result with a category and summary. If triage 502s, start Lemonade and pull the model, then retry — the rest of your integration is fine.

To eyeball the agent by hand without writing any code, run npx @amd-gaia/agent-email playground — it fetches the binary, starts the sidecar, and opens an interactive page where you can fire triage/draft and see a stack-health check.

For the full endpoint list, lifecycle internals, and connector details, see SPEC.md next to this file.

Aggregate score 83.4 / 100. View the canonical scorecard ↗

Email Triage — Eval Scorecard v0.3.0

Aggregate score: 83.4 (out of 100)

Recipe

Field	Value
Dataset	[tests/fixtures/email/ground_truth.json](tests/fixtures/email/ground_truth.json)
Description	Vendor-derived labelled email corpus for GAIA email-triage evaluation (FakeGmailBackend, schema-2.0 triage taxonomy: urgent / needs_response / fyi / promotional / personal); a deterministic, category-balanced subset of the vendor mailbox dataset
Dataset size	249 labeled examples
Test cases run	249
Methodology	gaia eval benchmark over the vendor-derived labelled corpus via FakeGmailBackend; no LLM judge. The full 249-email corpus is scored (GAIA_EMAIL_TRIAGE_MAX_MESSAGES lifts the interactive per-call scan cap for the eval so the whole balanced corpus is covered). Aggregate = within-one-bucket ACCEPTANCE accuracy (#1437): triage priority is ordinal (URGENT>NEEDS_RESPONSE>FYI>PROMOTIONAL), so a prediction is credited when it is exact or an adjacent bucket (

Metrics

- within_one_bucket_accuracy: 0.8340 × 1.0 - urgent_vs_not_accuracy: 0.7845 × 0.0 - urgent_recall: 0.9938 × 0.0 - personal_recall: 0.3636 × 0.0 - category_accuracy: 0.7684 × 0.0

Aggregate score recomputation

Formula: round(100 × Σ(weightᵢ × valueᵢ) / Σ(weightᵢ), 2)

Worked example:

round(100 × ((0.8340 × 1.0) + (0.7845 × 0.0) + (0.9938 × 0.0) + (0.3636 × 0.0) + (0.7684 × 0.0)) / 1.0, 2) = 83.4

A reader can reproduce this value from the aggregate.components in the front matter alone — no eval-harness access needed.

Reproduction

Run the following commands from the repository root:

# Prerequisites: install the eval extras and start a Lemonade Server
# with the model on AMD Ryzen AI hardware (Strix Halo recommended).
uv pip install -e ".[dev,eval,api]"
lemonade-server serve   # in a separate shell; must stay running

# Step 0: build the corpus from the committed seed. The mbox +
# ground_truth are GENERATED artifacts (gitignored), so a fresh
# checkout must materialise them before the benchmark can read them.
python tests/fixtures/email/generate_mbox.py

# Step 1: run the benchmark (requires the Lemonade Server above with the
# model loaded; AMD Ryzen AI / Strix Halo recommended)
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring \
GAIA_AGENT_TOOL_TIMEOUT=1800 \
PYTHONPATH="$(pwd)" \
gaia eval benchmark \
    --model Gemma-4-E4B-it-GGUF \
    --mbox-path tests/fixtures/email/synthetic_inbox.mbox \
    --ground-truth tests/fixtures/email/ground_truth.json \
    --limit 250 \
    --output-dir /tmp/email-eval

# Step 2: generate this scorecard from the benchmark output
PYTHONPATH="$(pwd)" \
python hub/agents/python/email/packaging/gen_scorecard.py \
    --benchmark-dir /tmp/email-eval \
    --ground-truth tests/fixtures/email/ground_truth.json \
    --limit 250

# Background, dataset details, a worked example, and metric
# definitions: see EVALUATION.md (next to this scorecard).

See eval-scorecard docs and the [adding-eval-scorecard skill](.claude/skills/adding-eval-scorecard/SKILL.md) for the full setup guide.

Environment

Field	Value
gaia_commit	8dad5985
lemonade_version	10.7.0
model	Gemma-4-E4B-it-GGUF
hardware	AMD Ryzen AI MAX+ (Strix Halo)

Category breakdown (pooled across all 3 runs)

_Each of the 249 test cases is scored once per run, so the totals below sum to test_cases_run × 3._

Category	Total	Correct	Accuracy
fyi	162	125	0.7716
needs_response	162	162	1.0000
personal	99	36	0.3636
promotional	162	103	0.6358
urgent	162	148	0.9136

Top confusions:

- promotional → urgent: 48 - personal → needs_response: 48 - fyi → needs_response: 37 - personal → urgent: 15 - urgent → needs_response: 12

Email Triage Agent — Evaluation Guide

How the Email Triage agent is evaluated, what the dataset is, and how to reproduce the numbers yourself. For the latest results, see SCORECARD.md; this document is the background and reproduction recipe behind them.

What this measures

The Email Triage agent sorts a Gmail inbox into priority/category buckets — URGENT, NEEDS_RESPONSE, FYI, PROMOTIONAL, PERSONAL — so nothing important gets buried. It runs 100% locally on AMD Ryzen AI: no cloud, no mail leaving the device.

This scorecard measures triage quality on a fixed, labelled corpus. The agent triages every email through a FakeGmailBackend (a synthetic inbox loaded from an mbox file — never a live mailbox), and each prediction is compared to a human/vendor label. The triage scoring is deterministic label-matching — not LLM-judged (predicted == expected; see quality_metrics.py), so these numbers are stable, cheap, and need no Claude/ANTHROPIC_API_KEY.

The agent itself uses a local LLM to classify each email; "not LLM-judged" refers to the scoring, which is exact label comparison.

The harness is gaia eval benchmark (src/gaia/eval/benchmark.py); it drives the unchanged agent and reuses the shared scorecard renderer.

A second eval that does use an LLM judge

The email agent also ships a separate voice-drafting quality eval (#1269): a Claude judge (eval_drafting_report.py, requires ANTHROPIC_API_KEY) scores each generated draft against a rubric. It is report-mode and independent of this scorecard — the 83.4 triage aggregate does not depend on it. If you only want to reproduce the scorecard below, you do not need the judge; if you want to run the drafting eval too, you do.

The dataset

The corpus is vendor-derived, not GAIA-synthesised, and fully reproducible from a single committed source of truth.

File	Role
`vendor_corpus_seed.jsonl`	Source of truth (committed) — a deterministic, category-balanced subset of the vendor's labelled mailbox dataset, already in the schema-2.0 taxonomy
`synthetic_inbox.mbox`	Generated (gitignored) — the mbox the eval loads via `FakeGmailBackend`
`ground_truth.json`	Generated (gitignored) — per-email labels, keyed by the Gmail-derived id `sha256(Message-ID)[:16]` so labels align 1:1 with `FakeGmailBackend`
`_schema.md`	Full corpus schema, provenance chain, PII policy, and category split

The two generated files are rebuilt from the seed on demand — never a live mailbox:

python tests/fixtures/email/generate_mbox.py           # seed -> mbox + ground_truth
python tests/fixtures/email/generate_mbox.py --verify   # check the two are in sync

Provenance chain (all reproducible):

vendor mailbox JSONL  --select_vendor_subset.py-->  vendor_corpus_seed.jsonl
                      --generate_mbox.py-->          synthetic_inbox.mbox + ground_truth.json

The corpus is category-balanced on purpose so per-category accuracy is meaningful and the scarce PERSONAL bucket stays measurable. Selection excludes real-person corpora (no personal PII enters a committed fixture); see _schema.md for the exact policy and counts.

A worked example (one labeled email)

1. Input — a seed record (source of truth):

{
  "id": "004d89d1-cba8-4045-b94b-b6cab756529b",
  "sender": "Hugo Petit <hugo.petit@lenovo.com>",
  "subject": "Ryzen AI Adoption Trends Across ThinkPad Lineup - Data Request",
  "category": "NEEDS_RESPONSE",
  "suggestedAction": "reply",
  "is_phishing": false,
  "source_dataset": "spamassassin"
}

generate_mbox.py writes this into the mbox and emits the matching ground-truth entry, keyed by the Gmail-derived id:

"<gmail-id>": {
  "category": "NEEDS_RESPONSE",
  "priority": "normal",
  "is_spam": false,
  "is_phishing": false,
  "suggested_action": "reply",
  "source_dataset": "spamassassin"
}

2. Output — the agent's prediction. At eval time the agent triages the email and returns a structured result (shape from llm_triage.py; the values below are illustrative for this email):

{
  "category": "NEEDS_RESPONSE",
  "is_spam": false,
  "confidence": 0.82,
  "reasoning": "Direct data request from a partner; expects a reply.",
  "suggested_action": "reply"
}

3. Scoring. The scorer compares the predicted category to the ground-truth category and records one row:

{ "id": "<gmail-id>", "predicted": "NEEDS_RESPONSE", "expected": "NEEDS_RESPONSE", "category_correct": true }

Because triage priority is ordinal (URGENT > NEEDS_RESPONSE > FYI > PROMOTIONAL), the headline metric credits an exact match or an adjacent bucket. For this email, predicting URGENT or FYI still counts toward the aggregate, while PROMOTIONAL (two buckets away) does not.

Understanding the metrics

Metric	In aggregate?	Meaning
within_one_bucket_accuracy	✅ headline	Share of emails whose predicted priority is exact or one bucket off — what a user feels: nothing urgent buried. The only metric in the aggregate.
category_accuracy	reported	Strict exact-match rate on the category label. Always lower than the headline; the harder bar.
urgent_recall	reported (anti-gaming floor)	Fraction of truly urgent emails caught. Keeps a model from inflating the headline by calling everything urgent.
urgent_vs_not_accuracy	reported	Binary urgent-vs-everything-else accuracy.
personal_recall	reported	Recall on the scarce `PERSONAL` bucket.

Only within_one_bucket_accuracy carries weight; the rest are shown with weight 0, so the published aggregate is recomputable as 100 × within_one_bucket_accuracy. The exact formula and a worked recomputation are in SCORECARD.md.

Reproducing the scorecard

The exact, version-stamped command that produced the current numbers lives in SCORECARD.md → Reproduction. It is auto-generated with that run's model, corpus, and limit, so it always matches the published score — this guide deliberately does not duplicate it (a hand-copy would drift). Run that block from a source checkout of amd/gaia; it installs the eval extras, starts a Lemonade Server, and builds the corpus from the committed seed before running the benchmark. You need AMD Ryzen AI hardware (Strix Halo recommended) — the npm package alone ships neither the corpus nor the harness.

A few things worth knowing before you run it:

GAIA_AGENT_TOOL_TIMEOUT=1800 — full-corpus triage is one long tool call (~17 min on a 4B local model); a lower timeout abandons it mid-run and scores 0 emails.
Run evals serially. Never run two gaia eval processes against one Lemonade Server — they race-evict each other's model. Use --experiments N for run-to-run variance instead of parallel runs.
Variance: --experiments 3 repeats the run and records mean / stdev / 95% CI (surfaced in the scorecard's acceptance_variance).

CI

Nightly (.github/workflows/test_email_agent_eval.yml) — runs the triage benchmark over the synthetic corpus on the self-hosted AMD (stx) pool, then the judge-scored voice-drafting eval (which needs ANTHROPIC_API_KEY; absent → loud skip, never a pass), and uploads a gate report. It is report mode: the quality / perf / drafting gates log and upload but do not fail the build (the threshold manifests under tests/fixtures/email/ ship enforce: false). Flip enforce: true in a manifest — data, not workflow — to start blocking on a breach.
Scorecard refresh (.github/workflows/email_scorecard_refresh.yml) — when the agent's LLM-affecting code or the corpus changes, re-runs the real eval, regenerates SCORECARD.md, and runs a same-version regression check.

Changelog

All notable changes to @amd-gaia/agent-email are documented here. The package follows SemVer: the MAJOR of the on-the-wire SCHEMA_VERSION is what checkVersion enforces at startup, so a contract MAJOR bump is always at least a package MINOR bump with a migration note.

0.4.0

Contract bumped to SCHEMA_VERSION 2.3. checkVersion is MAJOR-only, so the 2.x MAJOR is unchanged and existing clients keep connecting.

Changed

Triage returns a reply scaffold, not an empty draft (SCHEMA_VERSION 2.2 → 2.3). EmailTriageResult.draft is now a DraftScaffold ({ to, subject }) instead of a DraftReply — triage classifies and summarizes but never composes reply prose, so the draft.body it used to return was always "" regardless of model or provider. That empty field read as a bug ("the model failed to draft"), so it is dropped from the triage shape entirely. DraftReply (with body + attachments) is unchanged and remains the draft() / send() shape: to send a reply, compose the body yourself and call draft() for a full DraftReply + confirmation token. MAJOR is unchanged (the removed field carried no data), so checkVersion does not flag existing integrations; TypeScript consumers that destructured result.draft.body will see it typed away and should read the body from draft() instead.

Security

Caller authentication for the local sidecar API (#1706). The sidecar binds 127.0.0.1 and can send mail as the user, but its REST API had no caller authentication — any other local process, or a web page in the user's browser (via DNS-rebinding), could reach draft/send. spawnSidecar / startSidecar now mint a cryptographically-random per-session bearer token, hand it to the sidecar over the private GAIA_EMAIL_SIDECAR_TOKEN env channel, and bind it to sidecar.client; every /v1/email/* request must present Authorization: Bearer <token> or it is 401. A non-loopback Host is 400 and a non-loopback browser Origin is 403, closing DNS-rebinding / drive-by access. The draft→send confirmation-token gate is unchanged (it is payload-integrity, not caller-auth). EmailClient gains an authToken option; sidecar.authToken and generateSessionToken are exported for the construct-your-own-client / renderer-over-IPC paths. Wire-compatible: no contract change, SCHEMA_VERSION stays 2.2.

Added

Code-derived capability matrix (#2013). New committed CAPABILITY_MATRIX.md inventories every capability surface (52 internal agent-loop tools, 16 functional REST verbs, 4 MCP tools, 6 eval suites) with per-op eval coverage; a CI drift test regenerates and byte-compares it so the surfaces can no longer silently diverge. Doc-only for this package (referenced from README/SPEC); no wire or client change.
Readiness preflight — GET /v1/email/init (#1795). A green /health never meant "ready to triage": on a fresh host the binary boots fine but the first triage 502s until Lemonade is up and the model is pulled. The new endpoint probes the whole triage stack — Lemonade reachable and version-compatible and the triage model downloaded — and returns 200 when ready, 503 with an actionable hint when not (same InitResponse envelope either way). Read-only: no model pull. The companion POST /v1/email/init asks the running Lemonade to download the model and streams text/plain progress (it can't install Lemonade itself — a host prerequisite — so an unreachable server is a loud 503, not a silent no-op). New exported types: InitResponse, InitLemonadeStatus, InitModelStatus; no client wrapper yet (call with fetch). SCHEMA_VERSION stays 2.2.
Voice / style-matched drafting (#1607). The agent can now draft replies in the user's own voice instead of a neutral scaffold. build_voice_profile samples the user's Sent mail into a local style profile — top greetings / sign-offs, typical length, contraction & exclamation rate (derived features only, never raw content, stored on-device) — and the agent's system prompt injects that guidance every turn so draft_reply bodies match how the user writes; clear_voice_profile forgets it. Agent-loop only (chat / Agent UI / gaia email) — no REST endpoint, no npm client method, SCHEMA_VERSION stays 2.2.
Content-based spam detection (#1911). Spam detection previously keyed entirely off Gmail's own SPAM label — so it did nothing for Outlook or any non-Gmail mailbox and wasn't real detection. It's now provider-agnostic: a narrow mechanical prefilter (auto-generated sender addresses, freemail-domain impersonation) handles the clear-cut cases, and the local LLM makes the real content-vs-legitimate-marketing call on the rest. The is_spam signal on triage() keeps its shape — only its derivation changed — so SCHEMA_VERSION stays 2.2. The eval corpus was expanded to exercise it (spam examples 7 → 57, corpus → 299 messages) and the scorecard gains is_spam recall / precision / F1 as the primary spam metrics (plain accuracy is misleading on a minority class this size).
Stateful agent surface (/v1/email/agent/*, #1666). A session-scoped, conversational surface so a host can drive the full EmailTriageAgent over HTTP — memory, personalization, and every agent tool — instead of importing it in-process. This is what lets the Agent UI back its email experience with the packaged sidecar. Additive and not part of the frozen triage contract (it runs the agent loop, not the stateless EmailTriageService), so it does not itself move SCHEMA_VERSION. New endpoints: POST /v1/email/agent/session, DELETE /v1/email/agent/session/{id}, GET /v1/email/agent/session/{id}/history, POST /v1/email/agent/query (SSE stream of the agent loop), POST /v1/email/agent/confirm-tool (approve/deny a gated tool), POST /v1/email/agent/cancel, and the runtime memory toggle POST /v1/email/agent/memory + GET /v1/email/agent/memory/{id}. Not wrapped by the typed npm client yet.
Runtime memory enable/disable (#1666). EmailAgentConfig.memory_enabled (startup) and EmailTriageAgent.set_memory_enabled() (runtime, no restart) turn the agent's memory — inbox profiling, behavioral learning, preference persistence, and working-context injection — on or off, superseding the startup-only GAIA_MEMORY_DISABLED env var. Reachable over HTTP via the agent surface above; enabling memory that was never initialized (started with GAIA_MEMORY_DISABLED or Lemonade unreachable) returns 409 with an actionable message, never a silent no-op. The frozen binary now bundles FAISS (the memory index); embeddings still go over Lemonade HTTP, so torch/transformers stay excluded.
Follow-up tracking (#1606). The agent gains a read-only check_followups tool that scans the Sent folder of every connected mailbox and flags threads whose latest message is still the user's own outbound mail past a configurable window (default 3 days) — surfacing message id, recipient, subject, and age, most overdue first. Detection only: it never sends a nudge (any send stays confirmation-gated). The scan caps how many Sent messages it enumerates per mailbox (default 50, max 200); the result now also carries scan_truncated: true when a mailbox has more sent mail than that cap, so the caller knows older threads weren't checked. Agent-loop surface (chat / Agent UI / gaia email); the sidecar REST/MCP surface is unchanged and SCHEMA_VERSION stays 2.2.
Attachment handling (#1542). Real email has attachments; triage and replies that ignored them were incomplete. Read/triage now exposes attachment metadata — EmailMessage (request) and EmailTriageResult / DraftReply (response) carry an attachments array of { filename, mime_type, size_bytes, attachment_id? } — and draft / send accept an attachments array of { filename, mime_type, content_base64 } (standard base64, ≤ 25 MB decoded each) that reaches the mailbox as real MIME/Graph file attachments. The draft→send confirmation token binds each attachment's filename, MIME type, and content digest, so a confirmed payload can't have files swapped in or smuggled past the user. Fail-loud validation throughout: bad base64 / MIME / oversize → 422, mismatched attachment set → 403, Outlook > 3 MB (Graph simple-attach limit) → a loud error, never truncation. The agent's in-loop draft_reply / send_now tools gain an optional comma-separated attachments file-path parameter with the same fail-loud checks.
Scheduled send + snooze in the agent tool loop (#1609): the agent can now schedule a send for a future time ("send this tomorrow at 9am") and snooze a message out of the inbox until a chosen time. A scheduled send is user-confirmed at creation (literal recipient/subject/body + fire time), stored as a regular mailbox draft plus a persistent one-shot job, and fired at/after its time by the agent's scheduler; snooze archives now and re-adds INBOX at the chosen time. Both are cancellable before they fire, and a firing failure is recorded on the job and logged — never silently swallowed. Agent-loop only — no runtime/contract change: no new REST endpoints, no new npm surface in this package (see SPEC "Agent-loop capabilities not on the contract").
Triage action items now persist as a task list (#1605): triage() / triageBatch() write each extracted action item to the sidecar's local SQLite (~/.gaia/email/state.db), linked back to the source message_id (or thread_id for a thread) and de-duplicated per message on the normalized description — re-triaging a message never duplicates tasks. Side-effect only: the wire response, contract, and SCHEMA_VERSION are unchanged, and results without a message_id are not persisted. Read/complete surfaces arrive with GAIA's cross-agent task store (amd/gaia#1521); until then the store is the email-local email_tasks table.
Scheduled daily inbox briefing (#1608): the sidecar can now run the inbox pre-scan on a daily timer — no prompt, no live caller — and expose the result on the new GET /v1/email/briefing (additive). The briefing payload is the same email_pre_scan envelope as POST /v1/email/prescan, produced by the agent's own pre_scan_inbox path, plus a generated_at stamp. Off by default: opt in by launching the sidecar with GAIA_EMAIL_BRIEFING_ENABLED=true (fire time GAIA_EMAIL_BRIEFING_TIME, 24h local HH:MM, default 08:00; scan size GAIA_EMAIL_BRIEFING_MAX_MESSAGES, 1–100, default 25), e.g. via startSidecar({ env: {...} }). An invalid value fails sidecar startup loudly; the endpoint returns 404 until the first scheduled run. REST-only for now — no npm client wrapper method yet.

Fixed

MCP serverInfo.version now reports the real package version. The stdio MCP server's get_mcp_server_info had a hardcoded "1.0.0" placeholder; it now sources AGENT_VERSION from gaia_agent_email.version, so all three version surfaces (wheel metadata, GET /v1/email/version agentVersion, MCP server info) agree.
Hub manifest tools_count corrected 6 → 52 (gaia-agent.yaml + the in-code agent registration): the agent registers 52 @tool functions; the stale 6 under-reported the surface on the hub page and the Agent UI card.

0.3.0

Contract bumped to SCHEMA_VERSION 2.1 — additive, no triage shape change, so checkVersion (MAJOR-only) keeps accepting 2.0 clients.

Eval scorecard now measures acceptance, and the release gate enforces it (#1437, #1894): the SCORECARD.md aggregate is now within-one-bucket acceptance accuracy (triage priority is ordinal, so exact-or-adjacent buckets are credited — what users feel) instead of exact 4-way match. Measured 0.834 (3-run mean on Strix Halo / Gemma-4-E4B, 95% CI [0.821, 0.847]) vs the 0.80 bar (#1437); exact 4-way stays a reported secondary (0.77). The card now carries run-to-run variance/CI, and the release gate enforces the 0.80 bar plus an anti-gaming URGENT-recall floor and a variance-aware regression check. No runtime/contract change — eval + packaging only.
Batch triage endpoint (#1887): new POST /v1/email/triage/batch / client.triageBatch(req) beside the single-email endpoint, so a caller can triage up to 100 emails or threads in one request instead of one HTTP round-trip per message. The body carries an items array; the response carries a parallel results array, order-preserved, each entry holding exactly one of result or error. Per-item failures are isolated: HTTP 200 with every item errored is a valid response, so consumers MUST inspect each results[].error, not just the HTTP status. New npm surface: client.triageBatch(), the BatchTriageRequest / BatchTriageResponse / BatchItemResult / BatchItemError types, and the MAX_BATCH_SIZE constant. New MCP tool triage_email_batch. Purely additive — the single triage() / POST /v1/email/triage / MCP triage_email are unchanged.
Inbox search on the REST contract (#1781): new read-only POST /v1/email/search / client.search(req). The Agent UI lost live inbox search in the in-process agent rip-out (#1653); this restores it through the package. Lists messages matching a Gmail-style query/labels from the connected mailbox and returns metadata only (id, subject, sender, snippet, labels) — no body, no confirmation token. Needs a connected mailbox (503 if none, 400 if 2+).
Archive + phishing-quarantine are now on the REST contract (#1779). The Agent UI lost these in the #1653 in-process rip-out — they ran only in the agent loop. They're back through the package: POST /v1/email/{archive,quarantine} (and their unarchive/unquarantine reversals), plus POST /v1/email/confirm to mint the gate token. Both mutating actions are confirmation-token-gated exactly like send (a missing/invalid token → 403 before any backend call); both are reversible inside the 30s undo window (the reversal endpoints are ungated — they restore). Archive returns a batch_id undo handle and the post_archive_id so Outlook undo survives the folder-move id change (#1738). Quarantine is Gmail-only — an Outlook mailbox is refused with 400 rather than shipping a folder-move its label-based undo can't reverse. New client methods: confirmAction, archive, unarchive, quarantine, unquarantine. Contract SCHEMA_VERSION bumps 2.0 → 2.1 (additive — triage-shape unchanged).
Calendar surface on the REST contract (SCHEMA_VERSION 2.0 → 2.1, #1780). Restores view / create / respond for calendar events through the packaged sidecar so the Agent UI gets it back without the in-process agent. New client methods: listCalendarEvents, previewCalendarEvent, createCalendarEvent, respondToCalendarEvent (+ Calendar* types). Create is confirmation-gated exactly like send — mint a token with previewCalendarEvent, echo it to createCalendarEvent; without a valid payload-bound token the create is rejected (403). Additive and same-major (2.x), so a 2.0 client keeps working.
Inbox pre-scan over REST (#1778): new prescan(req?) client method → POST /v1/email/prescan. Reads recent inbox messages from the connected mailbox and returns the triage-card envelope (kind: "email_pre_scan" — urgent / actionable / suggested-archive rows + an informational count) the Agent UI's pre-scan card renders. Read-only; reuses the agent's own pre_scan_inbox classification path. Contract SCHEMA_VERSION → 2.1.

Verified before release: the darwin-arm64 binary was frozen with packaging/freeze.py, passed the no-Python smoke_test.py (OpenAPI surface + /version + /v1/email/triage all PASS), and was driven end-to-end through the published EmailClient/checkVersion — single triage() and triageBatch() both returned real, correctly-categorized Lemonade inference results. Full transcript in the release PR.

0.2.5

Sending from a mailbox connected with identity-only scopes now returns an actionable 4xx (naming the missing installed:email grant) instead of an opaque HTTP 500, so the playground no longer points users at Lemonade for what is really an OAuth-scope problem. The playground's mailbox connect now requests mail-send scopes (so connect → send works), and the send panel keeps every connected mailbox selectable while marking ones that lack mail-send access. No agent wire-contract change — SCHEMA_VERSION stays 2.0.

0.2.4

First fully-published release of this feature set. The whole-package zip download (#1843) is temporarily disabled: the ~177 MB all-platforms zip exceeds Cloudflare's edge upload limit, so the publish step rejected it (413) and blocked every prior attempt (0.2.1–0.2.3). The worker-side streaming approach was reverted; 0.2.4 ships the per-platform binaries + this npm client without the combined zip. Per-platform binaries remain individually downloadable from the Hub. No agent wire-contract change — SCHEMA_VERSION stays 2.0.

0.2.3

Re-cut of 0.2.2 after the Agent Hub worker was redeployed with the large-artifact streaming fix. 0.2.2 published its per-platform binaries but its whole-package zip and npm publish never completed (the live worker hadn't yet picked up the fix); 0.2.3 is the first fully-published release of this feature set. No agent wire-contract change — SCHEMA_VERSION stays 2.0.

0.2.2

Release-reliability fix. The 0.2.1 tag published the per-platform binaries to the Agent Hub but its npm publish never completed: the Hub Worker buffered the entire upload in memory, so the new ~177 MB whole-package zip exceeded Cloudflare's 128 MB per-Worker memory limit and the publish step 502'd before npm. 0.2.2 fixes that and is the first complete publish of the 0.2.1 feature set. No agent wire-contract change — SCHEMA_VERSION stays 2.0 and the client + REST/MCP surface are unchanged.

Fixed

Whole-package zip + npm publish now complete. The Agent Hub Worker (POST /publish) streams large application/octet-stream uploads straight to R2 with server-side SHA-256 verification instead of reading the whole body into memory, so the ~177 MB whole-package zip publishes without OOMing the Worker.

0.2.1

Adds the one-command playground launcher and automatic sidecar cleanup, and makes this README the single canonical agent README (hub + npm). No wire-contract change (SCHEMA_VERSION stays 2.0).

Added

npx @amd-gaia/agent-email playground — one-command launcher. Fetches the binary, starts the sidecar, and opens the browser to /v1/email/playground, running until Ctrl+C. --port <n> to bind elsewhere, --no-open to skip the browser, --out <dir> to choose the binary cache. Makes "try the agent" a single command instead of fetch → spawn → find-the-URL.
Automatic sidecar cleanup (autoCleanup, default on). startSidecar / spawnSidecar now reap the frozen sidecar's detached process tree when the host process exits, crashes (uncaughtException / unhandledRejection), or is interrupted (SIGINT / SIGTERM / SIGHUP) — so a skipped or missed shutdown() no longer leaves the binary running and holding its port. Pass autoCleanup: false to manage the lifecycle yourself; shutdown() stays the graceful, awaited path. A hard SIGKILL of the host process is the one case no in-process handler can catch.

Changed

This README is now the single canonical agent README (hub + npm). The release workflow publishes it to both, so the hub page and the npm listing no longer drift — the architecture diagram and the GAIA/npm install flow show up on hub.amd-gaia.ai/hub/email.
Architecture diagram loads from an in-repo raw image instead of a version-pinned hub URL that the publish pipeline didn't populate, so it renders on GitHub and npm before the binaries are uploaded.
Agent version is shown on the hub cards (listing + featured + detail).

0.2.0

Changed (breaking)

Contract SCHEMA_VERSION 1.0 → 2.0. The TS client and the frozen binary now agree on "2.0". A 0.1.x client against a 2.0 binary (or vice-versa) fails loudly at startSidecar with VersionMismatchError — upgrade both together. No expectedApiVersion override is needed once client and binary match.

Added

Browser-safe ./client subpath export. import { EmailClient } from "@amd-gaia/agent-email/client" exposes only zero-Node-dependency symbols, so the client bundles for a browser or Electron renderer. The . entry (binary fetch + sidecar spawn) stays Node-only.

0.1.0

Initial release: typed EmailClient, build-time fetch CLI (download + SHA-256 verify), and sidecar lifecycle helpers (spawnSidecar, waitForHealth, checkVersion, shutdown, startSidecar).

About Email Triage

@amd-gaia/agent-email

What the agent does

How it works

Install

Quick start

Triage many at once

Browser / Electron renderer

Authentication

Prerequisites

Interface

Scheduled daily briefing (#1608)

Lifecycle

Stateful agent surface (/v1/email/agent/*, 0.4.0)

Running in production

Errors & retries

Playground

Requirements

Troubleshooting

Reference

License

@amd-gaia/agent-email — Technical reference

Architecture

Concurrency & deployment

Authentication

REST API

Stateful agent surface (/v1/email/agent/*, 0.4.0)

Mailbox actions (archive / quarantine, schema 2.1)

Calendar (view / create / respond, schema 2.1)

Agent-loop capabilities not on the contract

Readiness vs liveness

Request shapes

Attachments (schema 2.2, #1542)

Triage response shape

Action-item task persistence (additive, #1605)

Batch triage shape (additive, #1887)

Inbox search shape

Lifecycle helpers

CLI

Connectors & auth

Browser / Electron renderer (./client)

Module format

Types

Platforms

License

Integrating @amd-gaia/agent-email

1. Install

2. Pick the right entry point

3. Fetch the binary and start the sidecar (Node)

4. Call the typed client

5. From a renderer (Electron / browser)

Stateful agent surface (/v1/email/agent/*, 0.4.0)

Running in a server / long-lived app

Prerequisites — the agent needs a local model

Gotchas (read before debugging)

Verify the integration

Email Triage — Eval Scorecard v0.3.0

Recipe

Metrics

Aggregate score recomputation

Reproduction

Environment

Category breakdown (pooled across all 3 runs)

Email Triage Agent — Evaluation Guide

What this measures

A second eval that does use an LLM judge

The dataset

A worked example (one labeled email)

Understanding the metrics

Reproducing the scorecard

CI

Changelog

0.4.0

Changed

Security

Added

Fixed

0.3.0

0.2.5

0.2.4

Stateful agent surface (`/v1/email/agent/*`, 0.4.0)

Stateful agent surface (`/v1/email/agent/*`, 0.4.0)

Browser / Electron renderer (`./client`)

Stateful agent surface (`/v1/email/agent/*`, 0.4.0)