[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7BYQJ0VRVB9Q3AKEX58BN9T":3,"skill-same:01M7BYQJ0VRVB9Q3AKEX58BN9T":208},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":15,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":13,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7BYQJ0VRVB9Q3AKEX58BN9T","integrate-agent-email",null,"Use when integrating the @amd-gaia\u002Fagent-email npm package — embedding the GAIA email agent (a local triage\u002Fdraft\u002Fsend sidecar) into a Node, TypeScript, or Electron app. Covers install, spawning the sidecar, calling the typed client, prerequisites, and the common gotchas.","secure-workflows\u002Fgaia","secure-workflows","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F311422533?v=4","01M7BYM925H8FAXM1DRD7F5DQD","01M7BYM92V01EZBAV87C93HNKX",0,"MIT","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: integrate-agent-email\ndescription: Use when integrating the @amd-gaia\u002Fagent-email npm package — embedding the GAIA email agent (a local triage\u002Fdraft\u002Fsend sidecar) into a Node, TypeScript, or Electron app. Covers install, spawning the sidecar, calling the typed client, prerequisites, and the common gotchas.\n---\n\n# Integrating @amd-gaia\u002Fagent-email\n\n`@amd-gaia\u002Fagent-email` embeds the GAIA email agent in a JS\u002FTS app. It triages,\ndrafts, and sends email **locally on AMD Ryzen AI** — no cloud LLM. This package is\nthe **client**: it downloads a frozen native **sidecar** binary, spawns it, and\ntalks to it over local HTTP. There is **no Python** and no separate GAIA install.\n\nFollow these steps to wire it into an app.\n\n> **This file is NOT one of the agent's own skills.** It is the integration\n> playbook — how *you* wire this npm package into an app. The sidecar separately\n> bundles six **Agent Skills** at `gaia_agent_email\u002Fskills\u002F\u003Cname>\u002FSKILL.md`, which\n> are instructions the *email agent itself* would load into its own prompt at\n> runtime — currently **disabled**, so none of them loads. Same filename,\n> different artifact: don't load those into your assistant, and don't ship this\n> one as an agent skill. See\n> [Skill sets](#skill-sets--disabled-in-this-release) below.\n\n## 1. Install\n\n```bash\nnpm install @amd-gaia\u002Fagent-email\n```\n\nThe package is **ESM-only** (`\"type\": \"module\"`). Use `import`, not `require`. From\na CommonJS file, use `await import(\"@amd-gaia\u002Fagent-email\")`.\n\n## 2. Pick the right entry point\n\n- **Node \u002F main process** → the default entry `@amd-gaia\u002Fagent-email`. It can\n  fetch the binary and spawn\u002Fown the sidecar (uses `node:fs`, `node:child_process`).\n- **Browser \u002F Electron renderer** → the `@amd-gaia\u002Fagent-email\u002Fclient` subpath. It\n  has zero Node built-ins and only talks to an already-running sidecar over HTTP.\n\nThe desktop pattern: spawn the sidecar **once** from the Node\u002Fmain process, then\ndrive it from the renderer via `.\u002Fclient`.\n\n## 3. Fetch the binary and start the sidecar (Node)\n\n```ts\nimport { fetchBinary, startSidecar, shutdown } from \"@amd-gaia\u002Fagent-email\";\n\n\u002F\u002F Build time (or first run): download + SHA-256-verify the platform binary.\nconst { binaryPath } = await fetchBinary({ outDir: \"resources\" });\n\n\u002F\u002F Runtime: spawn -> wait for \u002Fhealth -> version-check, in one call.\nconst sidecar = await startSidecar({ binaryPath, port: 8131 });\n\n\u002F\u002F ... use sidecar.client ...\n\nawait shutdown(sidecar); \u002F\u002F graceful stop — auto-cleanup also reaps on exit\n```\n\n- `fetchBinary` writes a verified binary into `outDir`. SHA-256 is mandatory; a\n  bad download is rejected and not left on disk. Run it at build time or guard it\n  to run once.\n- `startSidecar` throws if the binary can't start, never becomes healthy, or the\n  contract MAJOR version mismatches — and cleans up so a failed start leaks nothing.\n- The sidecar is auto-reaped when your process exits, crashes, or is signalled\n  (default `autoCleanup`), so a missed `shutdown` won't orphan the frozen binary's\n  child. `shutdown(sidecar)` is the graceful, awaited stop; `autoCleanup: false` opts out.\n\n## 4. Call the typed client\n\n```ts\nconst res = await sidecar.client.triage({\n  payload: {\n    kind: \"single\",\n    principal: { email: \"me@example.com\" },\n    message: {\n      message_id: \"m1\",\n      from: { name: \"Sarah Chen\", email: \"sarah@example.com\" },\n      subject: \"Prod incident follow-up\",\n      body: \"Please review the report and reply by Friday.\",\n    },\n  },\n});\nconsole.log(res.result.category, res.result.summary);\n```\n\nTo classify many messages at once, use `triageBatch` — an `items` array (1–100) in,\na parallel `results` array out, order-preserved. It's additive (the single `triage`\nabove is unchanged). Per-item failures isolate, so an HTTP 200 can still carry\nerrored items — inspect each `results[].error`, never just the status:\n\n```ts\nconst batch = await sidecar.client.triageBatch({\n  items: [\n    { kind: \"single\", principal: { email: \"me@example.com\" },\n      message: { message_id: \"m1\", from: { email: \"sarah@example.com\" },\n        subject: \"Prod incident\", body: \"Reply by Friday.\" } },\n  ],\n});\nfor (const r of batch.results) {\n  if (r.error) console.warn(`item ${r.index} failed: ${r.error.message}`);\n  else console.log(`item ${r.index}:`, r.result!.category);\n}\n```\n\nThe interface:\n\n| Call | Needs | Notes |\n|------|-------|-------|\n| `triage(req)` | Local LLM only | Classify \u002F summarize \u002F 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. |\n| `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`). |\n| `search(req)` | A connected mailbox | Read-only inbox search by `query`\u002F`labels`; returns message metadata (id, subject, sender, snippet, labels), no body. No token. No mailbox → 503, two+ → 400. |\n| `prescan(req?)` | A connected mailbox | Read-only inbox pre-scan → triage-card envelope (`kind: \"email_pre_scan\"`), whose `needs_you` (schema 2.11) is the ONE worklist the card renders — up to 5 things that need you, plus `bulk` for the filtered remainder. Also carries `suspicious`\u002F`suspicious_total` (schema 2.13): the phishing\u002Fspam-flagged subset of `actionable`, each item tagged `is_phishing`\u002F`is_spam`. No mailbox connected → 503; 2+ → 400. Heuristic-only, no Lemonade call. `NeedsYouItem.detail` is reserved on the wire but always empty today on every surface — see [`CHANGELOG.md`](.\u002FCHANGELOG.md). |\n| `draft(req)` | Nothing external | Returns a single-use confirmation token. Optional `attachments` (schema 2.2): `{ filename, mime_type, content_base64 }` each, ≤ 25 MB decoded. |\n| `send(req)` | Draft token + a connected mailbox | Gate fires first: no\u002Finvalid `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). |\n| `confirmAction(req)` | Nothing external | Mints a single-use token for `\"archive\"`\u002F`\"quarantine\"`, bound to the `(action, message_id)`. |\n| `archive(req)` | `confirm` token + a connected mailbox | Removes from inbox. Gate fires first (no\u002Finvalid token → 403). Returns a `batch_id` undo handle (+ `post_archive_id` for the Outlook id change). |\n| `unarchive(req)` | A connected mailbox | Restores within the 30s window (ungated — pass `batch_id`); expired\u002Funknown → 409. |\n| `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). |\n| `unquarantine(req)` | A connected mailbox | Restores prior labels within the 30s window (ungated — pass `action_id`); expired\u002Funknown → 409. |\n| `listCalendarEvents(opts?)` | Connected mailbox + calendar scope | Read-only view of the primary calendar. Optional `timeMin`\u002F`timeMax` — omitting both defaults to a forward window (now → +30 days); `provider` only when >1 account. Missing scope → 403 + reconnect CTA. |\n| `previewCalendarEvent(req)` | Nothing external | Mints a single-use confirmation token bound to the event (calendar analogue of `draft`). |\n| `createCalendarEvent(req)` | Preview token + connected calendar | Token gate fires first: no\u002Finvalid token → 403, then the calendar checks. |\n| `respondToCalendarEvent(req)` | Connected calendar | RSVP `accepted`\u002F`declined`\u002F`tentative` to an existing invite. |\n| `query(req)` | A connected mailbox (for mailbox tools) | The agent loop (schema 2.4): async iterator of the seven typed SSE events. You mint `run_id`; push the transcript slice in `context`. See \"Canonical agent-loop query\" below. |\n| `cancelQuery(runId)` | Nothing external | Cancel an in-flight `query()` run between steps (pass the `run_id` you minted). Not in flight → 404. |\n\n**Build the standalone surface (`triage`, `draft`, `confirmAction`,\n`previewCalendarEvent`) with zero connector setup.** The read-only `search` and\n`prescan` read the live inbox (a connected mailbox, no token); `send`, the mailbox\nactions (`archive` \u002F `quarantine`), and the calendar actions (view \u002F create \u002F respond)\nneed a connected mailbox whose relevant scope was granted. Mint the gate token with\n`draft` (for `send`), `confirmAction` (for `archive` \u002F `quarantine`), or\n`previewCalendarEvent` (for `createCalendarEvent`); `archive` and `quarantine` are\nreversible inside a 30s window via the ungated `unarchive` \u002F `unquarantine`. Every\nnon-2xx response throws `HttpError` (`status`, `url`, `bodyText`) — handle it; there is\nno silent null.\n\n**Scheduled daily briefing (#1608, REST-only):** the sidecar can run `prescan` on a\ndaily timer with no prompt. Off by default — launch with\n`startSidecar({ env: { GAIA_EMAIL_BRIEFING_ENABLED: \"true\" } })` (fire time\n`GAIA_EMAIL_BRIEFING_TIME`, 24h local `HH:MM`, default `08:00`), then pull the latest\nrun from `GET \u002Fv1\u002Femail\u002Fbriefing` with plain `fetch` (no client wrapper yet). 404\nuntil the first scheduled run; an invalid env value fails sidecar startup loudly.\n\n## 5. From a renderer (Electron \u002F browser)\n\nThe sidecar serves **same-origin only — no CORS**. A renderer on a different origin\n**cannot** fetch `http:\u002F\u002F127.0.0.1:8131` directly; the browser blocks it. So:\n\n- **Recommended:** spawn the sidecar in the Electron **main** process (step 3) and\n  expose `triage`\u002F`draft` to the renderer over your own IPC. Don't call the sidecar\n  from the renderer directly.\n- The `.\u002Fclient` entry (zero Node built-ins) is only usable from a **same-origin or\n  proxied** page:\n\n```ts\nimport { EmailClient } from \"@amd-gaia\u002Fagent-email\u002Fclient\";\n\u002F\u002F Pass the sidecar's session token (from sidecar.authToken in the main process,\n\u002F\u002F forwarded over IPC) — without it every \u002Fv1\u002Femail\u002F* call is 401.\nconst client = new EmailClient({ baseUrl: \"http:\u002F\u002F127.0.0.1:8131\", authToken });\n```\n\n## Canonical agent-loop query (`POST \u002Fv1\u002Femail\u002Fquery`, schema 2.6)\n\nThe v2 keystone (#2016): NL request in, the agent reasons and chains its tools, the\n**canonical Server-Sent Event types** out — `status` \u002F `token` \u002F `tool_call` \u002F\n`tool_result` \u002F `needs_confirmation` \u002F `needs_input` \u002F `final` \u002F `error`, terminated by\nexactly one `final` or `error`. This is the one loop every v2 front-door relays to. The **host\nmints `run_id`** and **pushes** the transcript slice in `context`, so the sidecar\nstays stateless. The typed client wraps it (#2097): `query()` returns an async\niterator of typed `QueryEvent`s; `cancelQuery(runId)` stops the run between steps:\n\n```ts\nconst runId = crypto.randomUUID(); \u002F\u002F host-minted; also the cancel handle\nfor await (const ev of sidecar.client.query({\n  query: \"Triage my inbox\",\n  run_id: runId,\n  context: [], \u002F\u002F pushed transcript slice; [] for a fresh conversation\n})) {\n  switch (ev.type) {\n    case \"status\":       console.log(ev.message); break;\n    case \"token\":        process.stdout.write(ev.delta); break;\n    case \"tool_call\":    console.log(`→ ${ev.tool}`, ev.args); break;\n    case \"tool_result\":  console.log(`← ${ev.tool}`, ev.data); break;\n    case \"needs_confirmation\": break; \u002F\u002F run then ends with a final refusal (D1)\n    case \"needs_input\":               \u002F\u002F PAUSED — answer, then keep iterating\n      await sidecar.client.respondToQuery(runId, ev.request_id, await askUser(ev));\n      break;\n    case \"final\":        console.log(ev.answer); break;   \u002F\u002F terminal\n    case \"error\":        console.error(ev.detail); break; \u002F\u002F terminal, verbatim\n    default:             console.warn(\"unsupported event\", ev); \u002F\u002F future additive type\n  }\n}\n\u002F\u002F Mid-run, from anywhere that knows runId:\n\u002F\u002F await sidecar.client.cancelQuery(runId);\n```\n\nRules an integration must respect:\n\n- **Mint `run_id` yourself** (`crypto.randomUUID()`) and keep it — it is the cancel\n  handle, valid from the instant the request is sent.\n- **Exactly one terminal event.** A terminal `error` is *yielded* (surface `detail`\n  verbatim); transport\u002Fcontract failures *throw* (`HttpError` non-2xx,\n  `QueryStreamError` for a non-SSE response \u002F malformed event \u002F stream that closes\n  without a terminal). Never treat iterator completion without a `final` as success —\n  the client already throws for you.\n- **Gate `can_answer_questions` on the peer's version.** Call `version()` first:\n  a sidecar below `apiVersion` 2.6 does not know the field and answers `422` to\n  every request carrying it — including `false`. Omit it below 2.6 and treat\n  mid-run questions as unavailable.\n- **Declare `can_answer_questions` honestly.** It defaults to `false`. Set it\n  `true` only when a human is watching a UI that renders the question; a one-shot\n  or batch job must leave it off, and then gets an immediate actionable refusal\n  instead of a run parked on a question nobody can see.\n- **Answer `needs_input`, do not restart.** The run is parked on the SAME stream.\n  Call `respondToQuery(runId, ev.request_id, value)` and keep iterating the existing\n  iterator — issuing a fresh `query()` abandons the paused run. `value` is an\n  option's `value` (its `label` also works) or free text when `allow_free_text`.\n  Render every option's `description`: the label alone does not tell the user what\n  they are agreeing to. When `sensitive` is set, mask the input and never log it.\n  Ignoring the question is safe but wasteful — the run ends with an `error` after\n  `timeout_seconds`.\n- **Handle the `default` branch.** A `type` outside the canonical vocabulary arrives as\n  `{ type: \"unknown\", eventType, raw }` — render an \"unsupported event\" placeholder or\n  log it; it is never silently dropped.\n- **Long runs are normal.** `timeoutMs` bounds time-to-first-response only. To abort\n  from the client side pass `query(req, { signal })` AND call `cancelQuery` so the\n  sidecar stops the loop, not just the socket.\n\nA confirmation-requiring step (a destructive tool such as `send_now`) emits\n`needs_confirmation` then ends with a `final` refusal pointing at the fixed-function\nroute — mint a token via `draft()`, then `send()` (stateless stub, epic decision D1;\n`confirm_url` omitted). That is an **approval** and stays terminal and deny-by-default;\na **question** (`needs_input`) is the resumable one. Do not treat them alike.\n\n**Mailbox setup is the agent's job now (#2469).** When the agent has no usable mailbox —\nnot connected, credentials broken, missing a scope, or connected-but-not-granted — it\nasks the user about that specific problem via `needs_input` and fixes it, rather than\nreturning an error telling them to run a CLI command. Two cases are worth knowing:\nthe connected-but-not-granted case needs no browser at all (a local permission write),\nand connecting Google still requires the user to supply their own OAuth client ID and\nsecret, so expect a `sensitive: true` question on that path.\n\n**Mail-required, calendar-optional (#2730).** Every setup\u002Freconnect path — this\nself-repair flow included — requests the full mail + calendar scope union at\nconsent time, but only the mail scopes gate whether the flow reports success. A\nuser who declines calendar still ends up with a working mailbox; calendar\ntools raise their own actionable error, naming the exact scope, the first time\none is actually called. Do not \"fix\" a self-repair flow that requests only\nmail scopes — that narrower request is the bug this issue removed, not a\nsimplification to reintroduce.\n\n## Stateful agent surface (`\u002Fv1\u002Femail\u002Fagent\u002F*`, 0.4.0)\n\nEverything above is **stateless** — you send a payload, the sidecar analyzes it, no\nmemory, no conversation. The sidecar also hosts a **session-scoped, conversational\nagent** that runs the full `EmailTriageAgent` (memory, personalization, every agent\ntool) over HTTP. This is the surface the Agent UI uses. It is **not wrapped by the\ntyped `EmailClient` yet** — call it directly with `fetch` against the sidecar's\n`baseUrl`:\n\n```js\nconst base = \"http:\u002F\u002F127.0.0.1:8131\";\n\u002F\u002F 1. Start a session (builds the agent; reports memory availability).\nawait fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fsession`, {\n  method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\" },\n  body: JSON.stringify({ session_id: \"s1\" }),\n});\n\n\u002F\u002F 2. Run a turn — the reply streams back as Server-Sent Events.\nconst res = await fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fquery`, {\n  method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\", accept: \"text\u002Fevent-stream\" },\n  body: JSON.stringify({ session_id: \"s1\", message: \"Triage my inbox\" }),\n});\nconst reader = res.body.getReader(); const dec = new TextDecoder(); let buf = \"\";\nfor (;;) {\n  const { value, done } = await reader.read(); if (done) break;\n  buf += dec.decode(value, { stream: true });\n  let i; while ((i = buf.indexOf(\"\\n\\n\")) >= 0) {\n    const line = buf.slice(0, i).split(\"\\n\").find(l => l.startsWith(\"data: \"));\n    buf = buf.slice(i + 2);\n    if (!line) continue;\n    const ev = JSON.parse(line.slice(6));           \u002F\u002F {type: \"thinking\"|\"step\"|\"permission_request\"|\"run_complete\"|...}\n    if (ev.type === \"permission_request\") {         \u002F\u002F a gated tool (send\u002Fforward\u002Fdelete\u002F...) is waiting\n      await fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fconfirm-tool`, {\n        method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\" },\n        body: JSON.stringify({ session_id: \"s1\", approved: true }),\n      });\n    }\n    if (ev.type === \"run_complete\") console.log(\"answer:\", ev.answer);\n  }\n}\n```\n\nOther endpoints: `POST \u002Fcancel`, `DELETE \u002Fsession\u002F{id}`, `GET \u002Fsession\u002F{id}\u002Fhistory`,\nand the runtime memory toggle `POST \u002Fmemory` + `GET \u002Fmemory\u002F{id}` (enabling memory that\nwas never initialized returns **409**, never a silent no-op). One turn at a time per\nsession — an overlapping `\u002Fquery` returns **409**. See `SPEC.md` for the full table.\n\n### Full autonomy (`\u002Fv1\u002Femail\u002Fagent\u002Fautonomy\u002F*`)\n\nThe agent can run **proactively** at the `earn_trust` level: it archives low-signal\n(promotional\u002Fspam) mail and marks FYI mail read on its own **where your explicit\npreferences already sanction it** (a low-priority sender, or a category you default to\narchive) or a sender\u002Fcategory has earned enough trust, and **always asks before anything\ndestructive** (send \u002F forward \u002F RSVP \u002F quarantine). There is no permanent-delete — the\nagent only ever moves mail to Trash, which is always reversible. Reply drafting is not yet\nwired into this proactive loop (the policy layer supports it, but no candidate reaches it\ntoday).\nTurn it on and inspect the earned trust:\n\n```js\n\u002F\u002F Turn on full autonomy (levels: off | suggest | earn_trust | full; \"off\" = kill switch)\nawait fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fautonomy`, {\n  method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\" },\n  body: JSON.stringify({ session_id: \"s1\", level: \"earn_trust\" }),\n});\n\n\u002F\u002F Run one observe→decide→act cycle now (the daemon\u002Fscheduler drives this in production)\nconst r = await fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fautonomy\u002Frun`, {\n  method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\" },\n  body: JSON.stringify({ session_id: \"s1\", max_messages: 25 }),\n});\nconst report = await r.json();\n\u002F\u002F { level, executed:[…], proposals:[…], decisions:[…], skipped }\n\u002F\u002F decisions[] explains EVERY candidate considered: { message_id, tool, action, outcome, reason, sender }\n\n\u002F\u002F Inspect the earned-trust ledger — autonomy is never a black box\nconst status = await (await fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fautonomy\u002Fs1`)).json();\n\u002F\u002F { level, enabled, trust_min_samples, trust_threshold, trusted_scope_count, scopes:[…] }\n```\n\nThe agent **learns from your corrections**: undoing an auto-executed action —\n`POST \u002Fv1\u002Femail\u002Fagent\u002Fautonomy\u002Fundo` with `{ session_id, action_id }` from the `executed[]`\nentry, or the conversational `undo_archive_batch` tool for a batch archive — is captured as\na negative outcome that pulls the sender\u002Fcategory back below the trust bar. (Positive-outcome\naccrual — trust *rising* as suggestions are accepted or left standing — is not yet wired, so\ntoday the ledger only ratchets trust down.) Every auto-action is reversible with undo. A bad\n`level` returns **400**; an unknown session returns **404**; undoing an unknown\u002Fexpired\n`action_id` returns **409**; `\u002Frun` while the level is `off` returns **409** too — it refuses\nrather than returning the same 200 shape a real, found-nothing cycle would (#2528).\n\nThe Python host also ships a thin-client CLI over this same surface:\n`gaia email autonomy {status|set-level|pause|resume|run|trust|kill}` (#2516).\n\n## Skill sets — disabled in this release\n\nThe sidecar bundles six Agent Skills (`personal`: `inbox-triage`,\n`newsletter-digest`, `travel-itinerary`; `work`: `inbox-triage`,\n`meeting-scheduling`, `action-item-extraction`, `escalation-routing`), but the\nagent's manifest currently declares **no sets**, so **none of them loads**. A\npersonal and a work mailbox get identical behaviour. This is deliberate: the\nskills are held back until an eval run shows they improve triage.\n\nWhat that means for your integration:\n\n- **Do not pass `--skill-set` or `GAIA_EMAIL_SKILL_SET`.** Any value fails at\n  startup with `... but this agent declares no skill sets — Agent Skills are\n  switched off in this build.` There is no working name. This is fail-loud\n  behaviour, not a bug to work around.\n- `GAIA_EMAIL_ACCOUNT_TYPE` still validates but selects nothing.\n- Nothing in the API changes either way — same endpoints, same tools, same\n  permissions. Re-enabling happens inside the agent's `gaia-agent.yaml`; your\n  code does not change.\n\n## Running in a server \u002F long-lived app\n\n- **`fetchBinary` is a build step**, not per request (network + SHA verify). Run it\n  once; `resolveBinaryPath` at runtime.\n- **Spawn once at boot**, hold the `Sidecar` handle for the process lifetime — never\n  per request.\n- **Low concurrency.** One local Lemonade model slot, so parallel `triage` calls\n  serialize. Cap inflight calls.\n- **Cleanup is automatic** (default `autoCleanup`): the sidecar's child is reaped on\n  exit\u002Fcrash\u002Fsignal. Call `shutdown` for a graceful stop, or `autoCleanup: false` to\n  wire signals yourself. The package does not restart a crashed sidecar.\n\n## Fast local iteration (when you need to fix the agent, not just call it)\n\nThe steps above spawn a **frozen** binary — you can't edit it. To debug or improve\nthe agent, run its **Python source** and attach the same client. The frozen binary\nis that source frozen, so the contract is identical; only the base URL changes.\n\n```bash\npip install -e hub\u002Fagents\u002Femail\u002Fpython     # editable install\ngaia-agent-email serve --reload            # source server on 127.0.0.1:8131, auto-reload\n```\n\n```ts\nimport { connectSidecar } from \"@amd-gaia\u002Fagent-email\";\n\u002F\u002F Attaches (health + version check), spawns nothing, token off in dev:\nconst dev = await connectSidecar({ baseUrl: \"http:\u002F\u002F127.0.0.1:8131\" });\nawait dev.client.triage({ payload: { \u002F* … *\u002F } });\n\u002F\u002F Edit the Python under gaia_agent_email\u002F, save → reload → re-run. Seconds.\n```\n\n`npx @amd-gaia\u002Fagent-email dev` launches the `serve` process for you\n(`--python \u003Cpath>` to use a specific venv). There's no `child` on the returned\nhandle and nothing to `shutdown()` — you own the `serve` process (Ctrl+C). Switch\nback to production by using `startSidecar` (frozen binary) instead of\n`connectSidecar`; the client calls are unchanged.\n\n## Prerequisites — the agent needs a local model\n\nThe sidecar runs the LLM via **Lemonade Server**, which this package does **not**\ninstall. Before `triage`\u002F`draft`\u002F`send` succeed, the host must have:\n\n1. A running Lemonade Server (`lemonade-server serve`).\n2. The model pulled (`gaia init` installs Lemonade and downloads the default model).\n\nUntil then the binary boots, but the first `triage` returns **HTTP 502**.\n\n## Gotchas (read before debugging)\n\n- **Every `\u002Fv1\u002Femail\u002F*` call needs the session token** (#1706). `sidecar.client`\n  carries it automatically; a client you construct yourself must pass `authToken`\n  (from `sidecar.authToken`) or every call is **401**. Absent or non-loopback\n  `Host` → 400,\n  non-loopback browser `Origin` → 403. `\u002Fhealth` · `\u002Fversion` · `\u002Fv1\u002Femail\u002Fspec` ·\n  `\u002Fv1\u002Femail\u002Fplayground` are exempt.\n- **`health()` is liveness-only.** A green `\u002Fhealth` means the REST surface is up,\n  NOT that triage will work. For real readiness call **`init()`** (`GET\n  \u002Fv1\u002Femail\u002Finit`, #1795) — it probes Lemonade + the triage model and returns the\n  `InitResponse` on both the ready (`200`) and not-ready (`503`) paths, so branch on\n  `.ready` \u002F read `.hint`. `POST \u002Fv1\u002Femail\u002Finit` streams a model-pull (no wrapper yet).\n- **HTTP 502 from `triage`** → Lemonade isn't running\u002Freachable, or the model isn't\n  pulled. It is not a bug in this package.\n- **Addresses are objects, not strings.** `to` (and `triage`'s `from` \u002F `principal`)\n  are `{ email, name? }`; `to` is a non-empty array of them. A plain string → 422.\n- **`send` needs the draft `confirmation_token`** (missing\u002Finvalid → 403), but it\n  takes **no OAuth token** — the mailbox is resolved from the host's GAIA connector\n  store (no mailbox connected → 503). The read-only `search` \u002F `prescan` resolve the\n  mailbox the same way (503 with none, 400 with 2+). Triage and draft need no connector.\n- **Attachments bind to the token** (schema 2.2). Re-send the exact `attachments`\n  array you drafted with — the metadata-only `draft` echo has no `content_base64`,\n  so spreading the echo into `send` loses the files. A swapped\u002Fextra\u002Fmissing\n  attachment → 403; bad base64, a malformed MIME type, or > 25 MB decoded → 422;\n  Outlook additionally rejects files over 3 MB (Graph simple-attach limit).\n- **`archive` \u002F `quarantine` are gated like `send`**, but their token comes from\n  `confirmAction` (not `draft`) and is bound to the `(action, message_id)` — a token\n  for one can't authorize the other. Undo with `unarchive` (pass the returned\n  `batch_id`) \u002F `unquarantine` (pass the `action_id`) **within 30s**; past the window\n  the reversal returns **409** (restore manually in the mail client). For Outlook,\n  use the `post_archive_id` from the archive response — the folder move changes the id.\n- **Cleanup is automatic by default** — the sidecar is reaped on exit\u002Fcrash\u002Fsignal;\n  only `autoCleanup: false` (or a hard `SIGKILL` of your process) can orphan the\n  child. `shutdown` stays the graceful stop.\n- **OAuth forward-out is daemon-only (sidecar contract 2.5, #2154).** The\n  `\u002Fv1\u002Fconnections\u002F{provider}` intake exists for the GAIA Agent UI daemon to\n  forward short-lived access tokens to the sidecar (the sidecar never holds the\n  refresh token). A standalone integrator using this package does **not** call it —\n  keep resolving the mailbox from the host's GAIA connector store as before. There\n  is no `client.forwardConnection()` method, by design.\n- **Some capabilities are agent-loop-only — no REST endpoint, no client method.**\n  Scheduled send \u002F snooze (#1609), **voice \u002F style-matched drafting** (#1607 —\n  `build_voice_profile` learns a local style profile from Sent mail so drafts\n  come out in the user's own voice), **follow-up tracking** (#1606 —\n  `check_followups` flags sent mail still awaiting a reply, detection only),\n  and **waiting-on-you detection** (#2581 — `list_waiting_on_you` flags\n  INBOUND mail awaiting the user's reply; it only qualifies a message that has\n  both a genuine ask\u002Fmeeting-time signal and corroboration that it's real\n  correspondence) all run in the agent tool loop. The REST contract has no\n  routes for them yet, so don't look for `client.scheduleSend()` \u002F\n  `client.snooze()` \u002F a voice, follow-up, or waiting-on-you method — they\n  don't exist (and none of these moves `SCHEMA_VERSION`).\n- **`--skill-set` \u002F `GAIA_EMAIL_SKILL_SET` always fail right now.** Agent Skills\n  are disabled in this release, so the agent declares no sets and every name is\n  invalid. Don't wire either into your spawn options.\n- **ESM-only.** `require(\"@amd-gaia\u002Fagent-email\")` fails; use `import` \u002F dynamic\n  `import()`.\n\n## Verify the integration\n\nA green path looks like: `fetchBinary` succeeds → `startSidecar` resolves →\n`client.triage(...)` returns a `result` with a `category` and `summary`. If\n`triage` 502s, start Lemonade and pull the model, then retry — the rest of your\nintegration is fine.\n\nTo eyeball the agent by hand without writing any code, run\n`npx @amd-gaia\u002Fagent-email playground` — it fetches the binary, starts the sidecar,\nand opens an interactive page where you can fire triage\u002Fdraft and see a stack-health\ncheck.\n\nFor the full endpoint list, lifecycle internals, and connector details, see\n`SPEC.md` next to this file.\n","# Integrating @amd-gaia\u002Fagent-email\n\n`@amd-gaia\u002Fagent-email` embeds the GAIA email agent in a JS\u002FTS app. It triages,\ndrafts, and sends email **locally on AMD Ryzen AI** — no cloud LLM. This package is\nthe **client**: it downloads a frozen native **sidecar** binary, spawns it, and\ntalks to it over local HTTP. There is **no Python** and no separate GAIA install.\n\nFollow these steps to wire it into an app.\n\n> **This file is NOT one of the agent's own skills.** It is the integration\n> playbook — how *you* wire this npm package into an app. The sidecar separately\n> bundles six **Agent Skills** at `gaia_agent_email\u002Fskills\u002F\u003Cname>\u002FSKILL.md`, which\n> are instructions the *email agent itself* would load into its own prompt at\n> runtime — currently **disabled**, so none of them loads. Same filename,\n> different artifact: don't load those into your assistant, and don't ship this\n> one as an agent skill. See\n> [Skill sets](#skill-sets--disabled-in-this-release) below.\n\n## 1. Install\n\n```bash\nnpm install @amd-gaia\u002Fagent-email\n```\n\nThe package is **ESM-only** (`\"type\": \"module\"`). Use `import`, not `require`. From\na CommonJS file, use `await import(\"@amd-gaia\u002Fagent-email\")`.\n\n## 2. Pick the right entry point\n\n- **Node \u002F main process** → the default entry `@amd-gaia\u002Fagent-email`. It can\n  fetch the binary and spawn\u002Fown the sidecar (uses `node:fs`, `node:child_process`).\n- **Browser \u002F Electron renderer** → the `@amd-gaia\u002Fagent-email\u002Fclient` subpath. It\n  has zero Node built-ins and only talks to an already-running sidecar over HTTP.\n\nThe desktop pattern: spawn the sidecar **once** from the Node\u002Fmain process, then\ndrive it from the renderer via `.\u002Fclient`.\n\n## 3. Fetch the binary and start the sidecar (Node)\n\n```ts\nimport { fetchBinary, startSidecar, shutdown } from \"@amd-gaia\u002Fagent-email\";\n\n\u002F\u002F Build time (or first run): download + SHA-256-verify the platform binary.\nconst { binaryPath } = await fetchBinary({ outDir: \"resources\" });\n\n\u002F\u002F Runtime: spawn -> wait for \u002Fhealth -> version-check, in one call.\nconst sidecar = await startSidecar({ binaryPath, port: 8131 });\n\n\u002F\u002F ... use sidecar.client ...\n\nawait shutdown(sidecar); \u002F\u002F graceful stop — auto-cleanup also reaps on exit\n```\n\n- `fetchBinary` writes a verified binary into `outDir`. SHA-256 is mandatory; a\n  bad download is rejected and not left on disk. Run it at build time or guard it\n  to run once.\n- `startSidecar` throws if the binary can't start, never becomes healthy, or the\n  contract MAJOR version mismatches — and cleans up so a failed start leaks nothing.\n- The sidecar is auto-reaped when your process exits, crashes, or is signalled\n  (default `autoCleanup`), so a missed `shutdown` won't orphan the frozen binary's\n  child. `shutdown(sidecar)` is the graceful, awaited stop; `autoCleanup: false` opts out.\n\n## 4. Call the typed client\n\n```ts\nconst res = await sidecar.client.triage({\n  payload: {\n    kind: \"single\",\n    principal: { email: \"me@example.com\" },\n    message: {\n      message_id: \"m1\",\n      from: { name: \"Sarah Chen\", email: \"sarah@example.com\" },\n      subject: \"Prod incident follow-up\",\n      body: \"Please review the report and reply by Friday.\",\n    },\n  },\n});\nconsole.log(res.result.category, res.result.summary);\n```\n\nTo classify many messages at once, use `triageBatch` — an `items` array (1–100) in,\na parallel `results` array out, order-preserved. It's additive (the single `triage`\nabove is unchanged). Per-item failures isolate, so an HTTP 200 can still carry\nerrored items — inspect each `results[].error`, never just the status:\n\n```ts\nconst batch = await sidecar.client.triageBatch({\n  items: [\n    { kind: \"single\", principal: { email: \"me@example.com\" },\n      message: { message_id: \"m1\", from: { email: \"sarah@example.com\" },\n        subject: \"Prod incident\", body: \"Reply by Friday.\" } },\n  ],\n});\nfor (const r of batch.results) {\n  if (r.error) console.warn(`item ${r.index} failed: ${r.error.message}`);\n  else console.log(`item ${r.index}:`, r.result!.category);\n}\n```\n\nThe interface:\n\n| Call | Needs | Notes |\n|------|-------|-------|\n| `triage(req)` | Local LLM only | Classify \u002F summarize \u002F 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. |\n| `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`). |\n| `search(req)` | A connected mailbox | Read-only inbox search by `query`\u002F`labels`; returns message metadata (id, subject, sender, snippet, labels), no body. No token. No mailbox → 503, two+ → 400. |\n| `prescan(req?)` | A connected mailbox | Read-only inbox pre-scan → triage-card envelope (`kind: \"email_pre_scan\"`), whose `needs_you` (schema 2.11) is the ONE worklist the card renders — up to 5 things that need you, plus `bulk` for the filtered remainder. Also carries `suspicious`\u002F`suspicious_total` (schema 2.13): the phishing\u002Fspam-flagged subset of `actionable`, each item tagged `is_phishing`\u002F`is_spam`. No mailbox connected → 503; 2+ → 400. Heuristic-only, no Lemonade call. `NeedsYouItem.detail` is reserved on the wire but always empty today on every surface — see [`CHANGELOG.md`](.\u002FCHANGELOG.md). |\n| `draft(req)` | Nothing external | Returns a single-use confirmation token. Optional `attachments` (schema 2.2): `{ filename, mime_type, content_base64 }` each, ≤ 25 MB decoded. |\n| `send(req)` | Draft token + a connected mailbox | Gate fires first: no\u002Finvalid `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). |\n| `confirmAction(req)` | Nothing external | Mints a single-use token for `\"archive\"`\u002F`\"quarantine\"`, bound to the `(action, message_id)`. |\n| `archive(req)` | `confirm` token + a connected mailbox | Removes from inbox. Gate fires first (no\u002Finvalid token → 403). Returns a `batch_id` undo handle (+ `post_archive_id` for the Outlook id change). |\n| `unarchive(req)` | A connected mailbox | Restores within the 30s window (ungated — pass `batch_id`); expired\u002Funknown → 409. |\n| `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). |\n| `unquarantine(req)` | A connected mailbox | Restores prior labels within the 30s window (ungated — pass `action_id`); expired\u002Funknown → 409. |\n| `listCalendarEvents(opts?)` | Connected mailbox + calendar scope | Read-only view of the primary calendar. Optional `timeMin`\u002F`timeMax` — omitting both defaults to a forward window (now → +30 days); `provider` only when >1 account. Missing scope → 403 + reconnect CTA. |\n| `previewCalendarEvent(req)` | Nothing external | Mints a single-use confirmation token bound to the event (calendar analogue of `draft`). |\n| `createCalendarEvent(req)` | Preview token + connected calendar | Token gate fires first: no\u002Finvalid token → 403, then the calendar checks. |\n| `respondToCalendarEvent(req)` | Connected calendar | RSVP `accepted`\u002F`declined`\u002F`tentative` to an existing invite. |\n| `query(req)` | A connected mailbox (for mailbox tools) | The agent loop (schema 2.4): async iterator of the seven typed SSE events. You mint `run_id`; push the transcript slice in `context`. See \"Canonical agent-loop query\" below. |\n| `cancelQuery(runId)` | Nothing external | Cancel an in-flight `query()` run between steps (pass the `run_id` you minted). Not in flight → 404. |\n\n**Build the standalone surface (`triage`, `draft`, `confirmAction`,\n`previewCalendarEvent`) with zero connector setup.** The read-only `search` and\n`prescan` read the live inbox (a connected mailbox, no token); `send`, the mailbox\nactions (`archive` \u002F `quarantine`), and the calendar actions (view \u002F create \u002F respond)\nneed a connected mailbox whose relevant scope was granted. Mint the gate token with\n`draft` (for `send`), `confirmAction` (for `archive` \u002F `quarantine`), or\n`previewCalendarEvent` (for `createCalendarEvent`); `archive` and `quarantine` are\nreversible inside a 30s window via the ungated `unarchive` \u002F `unquarantine`. Every\nnon-2xx response throws `HttpError` (`status`, `url`, `bodyText`) — handle it; there is\nno silent null.\n\n**Scheduled daily briefing (#1608, REST-only):** the sidecar can run `prescan` on a\ndaily timer with no prompt. Off by default — launch with\n`startSidecar({ env: { GAIA_EMAIL_BRIEFING_ENABLED: \"true\" } })` (fire time\n`GAIA_EMAIL_BRIEFING_TIME`, 24h local `HH:MM`, default `08:00`), then pull the latest\nrun from `GET \u002Fv1\u002Femail\u002Fbriefing` with plain `fetch` (no client wrapper yet). 404\nuntil the first scheduled run; an invalid env value fails sidecar startup loudly.\n\n## 5. From a renderer (Electron \u002F browser)\n\nThe sidecar serves **same-origin only — no CORS**. A renderer on a different origin\n**cannot** fetch `http:\u002F\u002F127.0.0.1:8131` directly; the browser blocks it. So:\n\n- **Recommended:** spawn the sidecar in the Electron **main** process (step 3) and\n  expose `triage`\u002F`draft` to the renderer over your own IPC. Don't call the sidecar\n  from the renderer directly.\n- The `.\u002Fclient` entry (zero Node built-ins) is only usable from a **same-origin or\n  proxied** page:\n\n```ts\nimport { EmailClient } from \"@amd-gaia\u002Fagent-email\u002Fclient\";\n\u002F\u002F Pass the sidecar's session token (from sidecar.authToken in the main process,\n\u002F\u002F forwarded over IPC) — without it every \u002Fv1\u002Femail\u002F* call is 401.\nconst client = new EmailClient({ baseUrl: \"http:\u002F\u002F127.0.0.1:8131\", authToken });\n```\n\n## Canonical agent-loop query (`POST \u002Fv1\u002Femail\u002Fquery`, schema 2.6)\n\nThe v2 keystone (#2016): NL request in, the agent reasons and chains its tools, the\n**canonical Server-Sent Event types** out — `status` \u002F `token` \u002F `tool_call` \u002F\n`tool_result` \u002F `needs_confirmation` \u002F `needs_input` \u002F `final` \u002F `error`, terminated by\nexactly one `final` or `error`. This is the one loop every v2 front-door relays to. The **host\nmints `run_id`** and **pushes** the transcript slice in `context`, so the sidecar\nstays stateless. The typed client wraps it (#2097): `query()` returns an async\niterator of typed `QueryEvent`s; `cancelQuery(runId)` stops the run between steps:\n\n```ts\nconst runId = crypto.randomUUID(); \u002F\u002F host-minted; also the cancel handle\nfor await (const ev of sidecar.client.query({\n  query: \"Triage my inbox\",\n  run_id: runId,\n  context: [], \u002F\u002F pushed transcript slice; [] for a fresh conversation\n})) {\n  switch (ev.type) {\n    case \"status\":       console.log(ev.message); break;\n    case \"token\":        process.stdout.write(ev.delta); break;\n    case \"tool_call\":    console.log(`→ ${ev.tool}`, ev.args); break;\n    case \"tool_result\":  console.log(`← ${ev.tool}`, ev.data); break;\n    case \"needs_confirmation\": break; \u002F\u002F run then ends with a final refusal (D1)\n    case \"needs_input\":               \u002F\u002F PAUSED — answer, then keep iterating\n      await sidecar.client.respondToQuery(runId, ev.request_id, await askUser(ev));\n      break;\n    case \"final\":        console.log(ev.answer); break;   \u002F\u002F terminal\n    case \"error\":        console.error(ev.detail); break; \u002F\u002F terminal, verbatim\n    default:             console.warn(\"unsupported event\", ev); \u002F\u002F future additive type\n  }\n}\n\u002F\u002F Mid-run, from anywhere that knows runId:\n\u002F\u002F await sidecar.client.cancelQuery(runId);\n```\n\nRules an integration must respect:\n\n- **Mint `run_id` yourself** (`crypto.randomUUID()`) and keep it — it is the cancel\n  handle, valid from the instant the request is sent.\n- **Exactly one terminal event.** A terminal `error` is *yielded* (surface `detail`\n  verbatim); transport\u002Fcontract failures *throw* (`HttpError` non-2xx,\n  `QueryStreamError` for a non-SSE response \u002F malformed event \u002F stream that closes\n  without a terminal). Never treat iterator completion without a `final` as success —\n  the client already throws for you.\n- **Gate `can_answer_questions` on the peer's version.** Call `version()` first:\n  a sidecar below `apiVersion` 2.6 does not know the field and answers `422` to\n  every request carrying it — including `false`. Omit it below 2.6 and treat\n  mid-run questions as unavailable.\n- **Declare `can_answer_questions` honestly.** It defaults to `false`. Set it\n  `true` only when a human is watching a UI that renders the question; a one-shot\n  or batch job must leave it off, and then gets an immediate actionable refusal\n  instead of a run parked on a question nobody can see.\n- **Answer `needs_input`, do not restart.** The run is parked on the SAME stream.\n  Call `respondToQuery(runId, ev.request_id, value)` and keep iterating the existing\n  iterator — issuing a fresh `query()` abandons the paused run. `value` is an\n  option's `value` (its `label` also works) or free text when `allow_free_text`.\n  Render every option's `description`: the label alone does not tell the user what\n  they are agreeing to. When `sensitive` is set, mask the input and never log it.\n  Ignoring the question is safe but wasteful — the run ends with an `error` after\n  `timeout_seconds`.\n- **Handle the `default` branch.** A `type` outside the canonical vocabulary arrives as\n  `{ type: \"unknown\", eventType, raw }` — render an \"unsupported event\" placeholder or\n  log it; it is never silently dropped.\n- **Long runs are normal.** `timeoutMs` bounds time-to-first-response only. To abort\n  from the client side pass `query(req, { signal })` AND call `cancelQuery` so the\n  sidecar stops the loop, not just the socket.\n\nA confirmation-requiring step (a destructive tool such as `send_now`) emits\n`needs_confirmation` then ends with a `final` refusal pointing at the fixed-function\nroute — mint a token via `draft()`, then `send()` (stateless stub, epic decision D1;\n`confirm_url` omitted). That is an **approval** and stays terminal and deny-by-default;\na **question** (`needs_input`) is the resumable one. Do not treat them alike.\n\n**Mailbox setup is the agent's job now (#2469).** When the agent has no usable mailbox —\nnot connected, credentials broken, missing a scope, or connected-but-not-granted — it\nasks the user about that specific problem via `needs_input` and fixes it, rather than\nreturning an error telling them to run a CLI command. Two cases are worth knowing:\nthe connected-but-not-granted case needs no browser at all (a local permission write),\nand connecting Google still requires the user to supply their own OAuth client ID and\nsecret, so expect a `sensitive: true` question on that path.\n\n**Mail-required, calendar-optional (#2730).** Every setup\u002Freconnect path — this\nself-repair flow included — requests the full mail + calendar scope union at\nconsent time, but only the mail scopes gate whether the flow reports success. A\nuser who declines calendar still ends up with a working mailbox; calendar\ntools raise their own actionable error, naming the exact scope, the first time\none is actually called. Do not \"fix\" a self-repair flow that requests only\nmail scopes — that narrower request is the bug this issue removed, not a\nsimplification to reintroduce.\n\n## Stateful agent surface (`\u002Fv1\u002Femail\u002Fagent\u002F*`, 0.4.0)\n\nEverything above is **stateless** — you send a payload, the sidecar analyzes it, no\nmemory, no conversation. The sidecar also hosts a **session-scoped, conversational\nagent** that runs the full `EmailTriageAgent` (memory, personalization, every agent\ntool) over HTTP. This is the surface the Agent UI uses. It is **not wrapped by the\ntyped `EmailClient` yet** — call it directly with `fetch` against the sidecar's\n`baseUrl`:\n\n```js\nconst base = \"http:\u002F\u002F127.0.0.1:8131\";\n\u002F\u002F 1. Start a session (builds the agent; reports memory availability).\nawait fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fsession`, {\n  method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\" },\n  body: JSON.stringify({ session_id: \"s1\" }),\n});\n\n\u002F\u002F 2. Run a turn — the reply streams back as Server-Sent Events.\nconst res = await fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fquery`, {\n  method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\", accept: \"text\u002Fevent-stream\" },\n  body: JSON.stringify({ session_id: \"s1\", message: \"Triage my inbox\" }),\n});\nconst reader = res.body.getReader(); const dec = new TextDecoder(); let buf = \"\";\nfor (;;) {\n  const { value, done } = await reader.read(); if (done) break;\n  buf += dec.decode(value, { stream: true });\n  let i; while ((i = buf.indexOf(\"\\n\\n\")) >= 0) {\n    const line = buf.slice(0, i).split(\"\\n\").find(l => l.startsWith(\"data: \"));\n    buf = buf.slice(i + 2);\n    if (!line) continue;\n    const ev = JSON.parse(line.slice(6));           \u002F\u002F {type: \"thinking\"|\"step\"|\"permission_request\"|\"run_complete\"|...}\n    if (ev.type === \"permission_request\") {         \u002F\u002F a gated tool (send\u002Fforward\u002Fdelete\u002F...) is waiting\n      await fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fconfirm-tool`, {\n        method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\" },\n        body: JSON.stringify({ session_id: \"s1\", approved: true }),\n      });\n    }\n    if (ev.type === \"run_complete\") console.log(\"answer:\", ev.answer);\n  }\n}\n```\n\nOther endpoints: `POST \u002Fcancel`, `DELETE \u002Fsession\u002F{id}`, `GET \u002Fsession\u002F{id}\u002Fhistory`,\nand the runtime memory toggle `POST \u002Fmemory` + `GET \u002Fmemory\u002F{id}` (enabling memory that\nwas never initialized returns **409**, never a silent no-op). One turn at a time per\nsession — an overlapping `\u002Fquery` returns **409**. See `SPEC.md` for the full table.\n\n### Full autonomy (`\u002Fv1\u002Femail\u002Fagent\u002Fautonomy\u002F*`)\n\nThe agent can run **proactively** at the `earn_trust` level: it archives low-signal\n(promotional\u002Fspam) mail and marks FYI mail read on its own **where your explicit\npreferences already sanction it** (a low-priority sender, or a category you default to\narchive) or a sender\u002Fcategory has earned enough trust, and **always asks before anything\ndestructive** (send \u002F forward \u002F RSVP \u002F quarantine). There is no permanent-delete — the\nagent only ever moves mail to Trash, which is always reversible. Reply drafting is not yet\nwired into this proactive loop (the policy layer supports it, but no candidate reaches it\ntoday).\nTurn it on and inspect the earned trust:\n\n```js\n\u002F\u002F Turn on full autonomy (levels: off | suggest | earn_trust | full; \"off\" = kill switch)\nawait fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fautonomy`, {\n  method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\" },\n  body: JSON.stringify({ session_id: \"s1\", level: \"earn_trust\" }),\n});\n\n\u002F\u002F Run one observe→decide→act cycle now (the daemon\u002Fscheduler drives this in production)\nconst r = await fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fautonomy\u002Frun`, {\n  method: \"POST\", headers: { \"content-type\": \"application\u002Fjson\" },\n  body: JSON.stringify({ session_id: \"s1\", max_messages: 25 }),\n});\nconst report = await r.json();\n\u002F\u002F { level, executed:[…], proposals:[…], decisions:[…], skipped }\n\u002F\u002F decisions[] explains EVERY candidate considered: { message_id, tool, action, outcome, reason, sender }\n\n\u002F\u002F Inspect the earned-trust ledger — autonomy is never a black box\nconst status = await (await fetch(`${base}\u002Fv1\u002Femail\u002Fagent\u002Fautonomy\u002Fs1`)).json();\n\u002F\u002F { level, enabled, trust_min_samples, trust_threshold, trusted_scope_count, scopes:[…] }\n```\n\nThe agent **learns from your corrections**: undoing an auto-executed action —\n`POST \u002Fv1\u002Femail\u002Fagent\u002Fautonomy\u002Fundo` with `{ session_id, action_id }` from the `executed[]`\nentry, or the conversational `undo_archive_batch` tool for a batch archive — is captured as\na negative outcome that pulls the sender\u002Fcategory back below the trust bar. (Positive-outcome\naccrual — trust *rising* as suggestions are accepted or left standing — is not yet wired, so\ntoday the ledger only ratchets trust down.) Every auto-action is reversible with undo. A bad\n`level` returns **400**; an unknown session returns **404**; undoing an unknown\u002Fexpired\n`action_id` returns **409**; `\u002Frun` while the level is `off` returns **409** too — it refuses\nrather than returning the same 200 shape a real, found-nothing cycle would (#2528).\n\nThe Python host also ships a thin-client CLI over this same surface:\n`gaia email autonomy {status|set-level|pause|resume|run|trust|kill}` (#2516).\n\n## Skill sets — disabled in this release\n\nThe sidecar bundles six Agent Skills (`personal`: `inbox-triage`,\n`newsletter-digest`, `travel-itinerary`; `work`: `inbox-triage`,\n`meeting-scheduling`, `action-item-extraction`, `escalation-routing`), but the\nagent's manifest currently declares **no sets**, so **none of them loads**. A\npersonal and a work mailbox get identical behaviour. This is deliberate: the\nskills are held back until an eval run shows they improve triage.\n\nWhat that means for your integration:\n\n- **Do not pass `--skill-set` or `GAIA_EMAIL_SKILL_SET`.** Any value fails at\n  startup with `... but this agent declares no skill sets — Agent Skills are\n  switched off in this build.` There is no working name. This is fail-loud\n  behaviour, not a bug to work around.\n- `GAIA_EMAIL_ACCOUNT_TYPE` still validates but selects nothing.\n- Nothing in the API changes either way — same endpoints, same tools, same\n  permissions. Re-enabling happens inside the agent's `gaia-agent.yaml`; your\n  code does not change.\n\n## Running in a server \u002F long-lived app\n\n- **`fetchBinary` is a build step**, not per request (network + SHA verify). Run it\n  once; `resolveBinaryPath` at runtime.\n- **Spawn once at boot**, hold the `Sidecar` handle for the process lifetime — never\n  per request.\n- **Low concurrency.** One local Lemonade model slot, so parallel `triage` calls\n  serialize. Cap inflight calls.\n- **Cleanup is automatic** (default `autoCleanup`): the sidecar's child is reaped on\n  exit\u002Fcrash\u002Fsignal. Call `shutdown` for a graceful stop, or `autoCleanup: false` to\n  wire signals yourself. The package does not restart a crashed sidecar.\n\n## Fast local iteration (when you need to fix the agent, not just call it)\n\nThe steps above spawn a **frozen** binary — you can't edit it. To debug or improve\nthe agent, run its **Python source** and attach the same client. The frozen binary\nis that source frozen, so the contract is identical; only the base URL changes.\n\n```bash\npip install -e hub\u002Fagents\u002Femail\u002Fpython     # editable install\ngaia-agent-email serve --reload            # source server on 127.0.0.1:8131, auto-reload\n```\n\n```ts\nimport { connectSidecar } from \"@amd-gaia\u002Fagent-email\";\n\u002F\u002F Attaches (health + version check), spawns nothing, token off in dev:\nconst dev = await connectSidecar({ baseUrl: \"http:\u002F\u002F127.0.0.1:8131\" });\nawait dev.client.triage({ payload: { \u002F* … *\u002F } });\n\u002F\u002F Edit the Python under gaia_agent_email\u002F, save → reload → re-run. Seconds.\n```\n\n`npx @amd-gaia\u002Fagent-email dev` launches the `serve` process for you\n(`--python \u003Cpath>` to use a specific venv). There's no `child` on the returned\nhandle and nothing to `shutdown()` — you own the `serve` process (Ctrl+C). Switch\nback to production by using `startSidecar` (frozen binary) instead of\n`connectSidecar`; the client calls are unchanged.\n\n## Prerequisites — the agent needs a local model\n\nThe sidecar runs the LLM via **Lemonade Server**, which this package does **not**\ninstall. Before `triage`\u002F`draft`\u002F`send` succeed, the host must have:\n\n1. A running Lemonade Server (`lemonade-server serve`).\n2. The model pulled (`gaia init` installs Lemonade and downloads the default model).\n\nUntil then the binary boots, but the first `triage` returns **HTTP 502**.\n\n## Gotchas (read before debugging)\n\n- **Every `\u002Fv1\u002Femail\u002F*` call needs the session token** (#1706). `sidecar.client`\n  carries it automatically; a client you construct yourself must pass `authToken`\n  (from `sidecar.authToken`) or every call is **401**. Absent or non-loopback\n  `Host` → 400,\n  non-loopback browser `Origin` → 403. `\u002Fhealth` · `\u002Fversion` · `\u002Fv1\u002Femail\u002Fspec` ·\n  `\u002Fv1\u002Femail\u002Fplayground` are exempt.\n- **`health()` is liveness-only.** A green `\u002Fhealth` means the REST surface is up,\n  NOT that triage will work. For real readiness call **`init()`** (`GET\n  \u002Fv1\u002Femail\u002Finit`, #1795) — it probes Lemonade + the triage model and returns the\n  `InitResponse` on both the ready (`200`) and not-ready (`503`) paths, so branch on\n  `.ready` \u002F read `.hint`. `POST \u002Fv1\u002Femail\u002Finit` streams a model-pull (no wrapper yet).\n- **HTTP 502 from `triage`** → Lemonade isn't running\u002Freachable, or the model isn't\n  pulled. It is not a bug in this package.\n- **Addresses are objects, not strings.** `to` (and `triage`'s `from` \u002F `principal`)\n  are `{ email, name? }`; `to` is a non-empty array of them. A plain string → 422.\n- **`send` needs the draft `confirmation_token`** (missing\u002Finvalid → 403), but it\n  takes **no OAuth token** — the mailbox is resolved from the host's GAIA connector\n  store (no mailbox connected → 503). The read-only `search` \u002F `prescan` resolve the\n  mailbox the same way (503 with none, 400 with 2+). Triage and draft need no connector.\n- **Attachments bind to the token** (schema 2.2). Re-send the exact `attachments`\n  array you drafted with — the metadata-only `draft` echo has no `content_base64`,\n  so spreading the echo into `send` loses the files. A swapped\u002Fextra\u002Fmissing\n  attachment → 403; bad base64, a malformed MIME type, or > 25 MB decoded → 422;\n  Outlook additionally rejects files over 3 MB (Graph simple-attach limit).\n- **`archive` \u002F `quarantine` are gated like `send`**, but their token comes from\n  `confirmAction` (not `draft`) and is bound to the `(action, message_id)` — a token\n  for one can't authorize the other. Undo with `unarchive` (pass the returned\n  `batch_id`) \u002F `unquarantine` (pass the `action_id`) **within 30s**; past the window\n  the reversal returns **409** (restore manually in the mail client). For Outlook,\n  use the `post_archive_id` from the archive response — the folder move changes the id.\n- **Cleanup is automatic by default** — the sidecar is reaped on exit\u002Fcrash\u002Fsignal;\n  only `autoCleanup: false` (or a hard `SIGKILL` of your process) can orphan the\n  child. `shutdown` stays the graceful stop.\n- **OAuth forward-out is daemon-only (sidecar contract 2.5, #2154).** The\n  `\u002Fv1\u002Fconnections\u002F{provider}` intake exists for the GAIA Agent UI daemon to\n  forward short-lived access tokens to the sidecar (the sidecar never holds the\n  refresh token). A standalone integrator using this package does **not** call it —\n  keep resolving the mailbox from the host's GAIA connector store as before. There\n  is no `client.forwardConnection()` method, by design.\n- **Some capabilities are agent-loop-only — no REST endpoint, no client method.**\n  Scheduled send \u002F snooze (#1609), **voice \u002F style-matched drafting** (#1607 —\n  `build_voice_profile` learns a local style profile from Sent mail so drafts\n  come out in the user's own voice), **follow-up tracking** (#1606 —\n  `check_followups` flags sent mail still awaiting a reply, detection only),\n  and **waiting-on-you detection** (#2581 — `list_waiting_on_you` flags\n  INBOUND mail awaiting the user's reply; it only qualifies a message that has\n  both a genuine ask\u002Fmeeting-time signal and corroboration that it's real\n  correspondence) all run in the agent tool loop. The REST contract has no\n  routes for them yet, so don't look for `client.scheduleSend()` \u002F\n  `client.snooze()` \u002F a voice, follow-up, or waiting-on-you method — they\n  don't exist (and none of these moves `SCHEMA_VERSION`).\n- **`--skill-set` \u002F `GAIA_EMAIL_SKILL_SET` always fail right now.** Agent Skills\n  are disabled in this release, so the agent declares no sets and every name is\n  invalid. Don't wire either into your spawn options.\n- **ESM-only.** `require(\"@amd-gaia\u002Fagent-email\")` fails; use `import` \u002F dynamic\n  `import()`.\n\n## Verify the integration\n\nA green path looks like: `fetchBinary` succeeds → `startSidecar` resolves →\n`client.triage(...)` returns a `result` with a `category` and `summary`. If\n`triage` 502s, start Lemonade and pull the model, then retry — the rest of your\nintegration is fine.\n\nTo eyeball the agent by hand without writing any code, run\n`npx @amd-gaia\u002Fagent-email playground` — it fetches the binary, starts the sidecar,\nand opens an interactive page where you can fire triage\u002Fdraft and see a stack-health\ncheck.\n\nFor the full endpoint list, lifecycle internals, and connector details, see\n`SPEC.md` next to this file.\n",{"name":5,"description":7},"main","11039b64e036dca33313350b4cd1d6c2a791eb15","hub\u002Fagents\u002Femail\u002Fnpm","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia","https:\u002F\u002Fgithub.com\u002Fsecure-workflows","2026-10-26 10:48:34",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add secure-workflows\u002Fgaia --skill integrate-agent-email",{"tool":36,"command":37},"bunx","bunx skills add secure-workflows\u002Fgaia --skill integrate-agent-email",{"tool":39,"command":40},"pnpm","pnpm dlx skills add secure-workflows\u002Fgaia --skill integrate-agent-email","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002FSKILL.md",true,[44,50,56,60,66,70,74,80,84,88,92,96,100,104,108,112,116,120,124,128,132,136,140,144,148,152,156,160,164,168,172,176,180,184,188,192,196,200,204],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},".gitignore","OTHER","其他",49,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002F.gitignore",{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"assets\u002Farchitecture.html","ASSET","资产文件",8851,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fassets\u002Farchitecture.html",{"path":57,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":58,"sourceHtmlUrl":59},"assets\u002Farchitecture.webp",86374,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fassets\u002Farchitecture.webp",{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"binaries.lock.json","REFERENCE","参考文档",859,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fbinaries.lock.json",{"path":67,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":68,"sourceHtmlUrl":69},"CHANGELOG.md",28864,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002FCHANGELOG.md",{"path":71,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":72,"sourceHtmlUrl":73},"EVALUATION.md",4927,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002FEVALUATION.md",{"path":75,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":78,"sourceHtmlUrl":79},"examples\u002Fdemo.mjs","SCRIPT","脚本",10873,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fexamples\u002Fdemo.mjs",{"path":81,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":83,"sourceHtmlUrl":15},"LICENSE","许可证",1083,{"path":85,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":86,"sourceHtmlUrl":87},"package-lock.json",61693,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fpackage-lock.json",{"path":89,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":90,"sourceHtmlUrl":91},"package.json",1755,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fpackage.json",{"path":93,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":94,"sourceHtmlUrl":95},"README.md",8883,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002FREADME.md",{"path":97,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":98,"sourceHtmlUrl":99},"SCORECARD.md",10859,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002FSCORECARD.md",{"path":101,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":102,"sourceHtmlUrl":103},"SPEC.md",58955,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002FSPEC.md",{"path":105,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":106,"sourceHtmlUrl":107},"src\u002Fcli.ts",15780,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Fcli.ts",{"path":109,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":110,"sourceHtmlUrl":111},"src\u002Fclient-entry.ts",1285,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Fclient-entry.ts",{"path":113,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":114,"sourceHtmlUrl":115},"src\u002Fclient.ts",26627,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Fclient.ts",{"path":117,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":118,"sourceHtmlUrl":119},"src\u002Ferrors.ts",1726,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Ferrors.ts",{"path":121,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":122,"sourceHtmlUrl":123},"src\u002Ffetch.ts",7355,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Ffetch.ts",{"path":125,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":126,"sourceHtmlUrl":127},"src\u002Findex.ts",1874,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Findex.ts",{"path":129,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":130,"sourceHtmlUrl":131},"src\u002Flifecycle.ts",19526,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Flifecycle.ts",{"path":133,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":134,"sourceHtmlUrl":135},"src\u002Flogger.ts",1560,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Flogger.ts",{"path":137,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":138,"sourceHtmlUrl":139},"src\u002Fplatform.ts",4030,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Fplatform.ts",{"path":141,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":142,"sourceHtmlUrl":143},"src\u002Fsse.ts",3011,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Fsse.ts",{"path":145,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":146,"sourceHtmlUrl":147},"src\u002Ftypes.ts",55941,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Ftypes.ts",{"path":149,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":150,"sourceHtmlUrl":151},"src\u002Furl.ts",832,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fsrc\u002Furl.ts",{"path":153,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":154,"sourceHtmlUrl":155},"test\u002Fbrowser-entry.test.ts",3560,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Fbrowser-entry.test.ts",{"path":157,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":158,"sourceHtmlUrl":159},"test\u002Fcli.test.ts",3440,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Fcli.test.ts",{"path":161,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":162,"sourceHtmlUrl":163},"test\u002Fclient.test.ts",26926,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Fclient.test.ts",{"path":165,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":166,"sourceHtmlUrl":167},"test\u002Fconnect.test.ts",3511,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Fconnect.test.ts",{"path":169,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":170,"sourceHtmlUrl":171},"test\u002Ffetch.test.ts",5072,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Ffetch.test.ts",{"path":173,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":174,"sourceHtmlUrl":175},"test\u002Ffixtures\u002Fquery_test_server.py",5706,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Ffixtures\u002Fquery_test_server.py",{"path":177,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":178,"sourceHtmlUrl":179},"test\u002Flifecycle-auth.test.ts",3720,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Flifecycle-auth.test.ts",{"path":181,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":182,"sourceHtmlUrl":183},"test\u002Flifecycle-cleanup.test.ts",6755,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Flifecycle-cleanup.test.ts",{"path":185,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":186,"sourceHtmlUrl":187},"test\u002Fquery-integration.test.ts",6421,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Fquery-integration.test.ts",{"path":189,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":190,"sourceHtmlUrl":191},"test\u002Fquery.test.ts",12936,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Fquery.test.ts",{"path":193,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":194,"sourceHtmlUrl":195},"test\u002Fsse.test.ts",3424,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Fsse.test.ts",{"path":197,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":198,"sourceHtmlUrl":199},"test\u002Fversion-check.test.ts",1819,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftest\u002Fversion-check.test.ts",{"path":201,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":202,"sourceHtmlUrl":203},"tsconfig.json",565,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Ftsconfig.json",{"path":205,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":206,"sourceHtmlUrl":207},"vitest.config.ts",265,"https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Fhub\u002Fagents\u002Femail\u002Fnpm\u002Fvitest.config.ts",[209,216,223,230,237,244],{"skillNo":210,"name":211,"nameZh":6,"description":212,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":213,"categories":214,"keywords":215,"publishedAt":19},"01M7BYXGPPQJGVVD0DPS2WK3FS","web-search","Search the web via the Brave Search API. Use when the user asks about current events or external facts.","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fweb-search\u002FSKILL.md",[],[],{"skillNo":217,"name":218,"nameZh":6,"description":219,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":220,"categories":221,"keywords":222,"publishedAt":19},"01M7BYXDF2TM5JPMEQKMMHW0VJ","triage-support-ticket","Triage an inbound support ticket end to end. Use when the user pastes a support ticket or asks to triage one.","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Ftriage-support-ticket\u002FSKILL.md",[],[],{"skillNo":224,"name":225,"nameZh":6,"description":226,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":227,"categories":228,"keywords":229,"publishedAt":19},"01M7BYXAHWNBMJ8Y1Q51EZ53K7","tool-mismatch","Declares a tool its tools.py never registers. Used to prove validation fails loudly with no partial load.","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Ftool-mismatch\u002FSKILL.md",[],[],{"skillNo":231,"name":232,"nameZh":6,"description":233,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":234,"categories":235,"keywords":236,"publishedAt":19},"01M7BYX6CZ63AM6HB90PPNXKF7","report-archive","Archive a generated report to the user's reports folder and register it with the team's report index. Use when the user asks to file, archive, or publish a finished report.","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Freport-archive\u002FSKILL.md",[],[],{"skillNo":238,"name":239,"nameZh":6,"description":240,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":241,"categories":242,"keywords":243,"publishedAt":19},"01M7BYX4PM4HGNZ0QBZ54BTG1N","local-capability","Writes files on the local workspace. Used to prove Phase 1 refuses local-capability permissions.","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Flocal-capability\u002FSKILL.md",[],[],{"skillNo":245,"name":246,"nameZh":6,"description":247,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":248,"categories":249,"keywords":250,"publishedAt":19},"01M7BYX1KVPKHHZ5Z3R3BB0QQA","incident-review","Run an incident postmortem. Stands in for a Claude Code skill library imported read-only from .claude\u002Fskills\u002F.","https:\u002F\u002Fgithub.com\u002Fsecure-workflows\u002Fgaia\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fincident-review\u002FSKILL.md",[],[]]