heyquilt 0.3.108 → 0.3.116

package/src/voice.js

@@ -0,0 +1,184 @@
+// Voice in a session (plans/voice.md). Who is in the call, muted or not, and the call setup
+// (each pair's WebRTC offer and answer) travel in presence, so the relay needs nothing new.
+// The audio itself goes from app window to app window, never through the relay or this
+// process. What people say, when the owner turned transcripts on and they agreed, is kept as
+// lines in the session's document for everyone, agents included, to read.
+import crypto from 'node:crypto'
+
+// One offer or answer with its gathered addresses is a few kilobytes; anything far bigger isn't one.
+export const MAX_SDP = 16 * 1024
+// Signals one app keeps out at once: one per person in the call.
+export const MAX_SIGNALS = 16
+// A transcript line: one clip of speech, cut at a pause.
+export const MAX_LINE = 2000
+// Lines the session keeps; older ones go as new ones come.
+export const MAX_LINES = 5000
+// Lines of the call going on now that the app shows as they come.
+export const RECENT = 3
+// Everyone connects to everyone else, so a call holds this many people before the audio suffers.
+export const MAX_IN_CALL = 6
+export const CALL_FULL = `This call is full: calls hold ${MAX_IN_CALL} people for now.`
+const CALL = /^[A-Za-z0-9_-]{1,40}$/
+
+/** A signal for one person: an offer or an answer (`n` names the offer it answers), with or without its SDP. */
+export function cleanSignal (raw) {
+  if (!raw || typeof raw !== 'object') return null
+  if (raw.t !== 'offer' && raw.t !== 'answer') return null
+  if (typeof raw.n !== 'string' || !/^[A-Za-z0-9]{1,32}$/.test(raw.n)) return null
+  const out = { t: raw.t, n: raw.n }
+  if (raw.sdp !== undefined) {
+    if (typeof raw.sdp !== 'string' || !raw.sdp || raw.sdp.length > MAX_SDP) return null
+    out.sdp = raw.sdp
+  }
+  return out
+}
+
+/** Our voice presence, cleaned: null when not in voice. */
+export function cleanVoice (raw) {
+  if (!raw || typeof raw !== 'object' || raw.in !== true) return null
+  const sig = {}
+  if (raw.sig && typeof raw.sig === 'object') {
+    for (const [id, s] of Object.entries(raw.sig).slice(0, MAX_SIGNALS)) {
+      const c = /^\d{1,12}$/.test(id) ? cleanSignal(s) : null
+      if (c) sig[id] = c
+    }
+  }
+  return {
+    in: true,
+    muted: raw.muted === true,
+    since: Number.isFinite(raw.since) && raw.since > 0 ? Math.floor(raw.since) : 0,
+    call: typeof raw.call === 'string' && CALL.test(raw.call) ? raw.call : '',
+    // This person's app sends their speech to the transcript (they agreed, and the owner turned it on).
+    ...(raw.transcribing === true ? { transcribing: true } : {}),
+    sig
+  }
+}
+
+/** A new call's id, when nobody is in voice yet. */
+export function newCallId (now = Date.now()) {
+  return `${now.toString(36)}-${crypto.randomBytes(4).toString('hex')}`
+}
+
+/** Whether transcripts are on: the owner's switch, in the session document. A switch set by anyone else counts for nothing. */
+export function transcribeSetting (doc, members = []) {
+  const v = doc.getMap('voiceSettings').get('transcribe')
+  if (!v || typeof v !== 'object') return { on: false }
+  const owner = (members || []).find((m) => m && m.role === 'owner')
+  if (!owner || v.by !== owner.name) return { on: false }
+  return { on: v.on === true, by: v.by, ts: Number(v.ts) || 0 }
+}
+
+/** The owner turns transcripts on or off for everyone in the session. */
+export function setTranscribe (doc, { on, by, now = Date.now() }) {
+  doc.getMap('voiceSettings').set('transcribe', { on: !!on, by, ts: now })
+}
+
+/** One person's line of speech in a call's transcript. */
+export function addLine (doc, { call, by, text, now = Date.now() }) {
+  const t = String(text || '').replace(/\s+/g, ' ').trim().slice(0, MAX_LINE)
+  if (!t) return null
+  if (typeof call !== 'string' || !CALL.test(call)) throw new Error('That is not a call.')
+  const line = { id: crypto.randomBytes(8).toString('hex'), call, by, text: t, ts: now }
+  const lines = doc.getArray('voiceLines')
+  doc.transact(() => {
+    lines.push([line])
+    const over = lines.length - MAX_LINES
+    if (over > 0) lines.delete(0, over)
+  })
+  return line
+}
+
+/**
+ * Transcript lines, oldest first: of one call, or after a time, or the most recent `limit`.
+ * `calls` lists each call once with who spoke and when it started and ended.
+ */
+export function readLines (doc, { call = '', since = 0, limit = 200 } = {}) {
+  const all = doc.getArray('voiceLines').toArray().filter((l) => l && typeof l.text === 'string' && typeof l.call === 'string')
+  const calls = new Map()
+  for (const l of all) {
+    const c = calls.get(l.call) || { call: l.call, start: l.ts, end: l.ts, people: [], lines: 0 }
+    c.start = Math.min(c.start, l.ts)
+    c.end = Math.max(c.end, l.ts)
+    if (!c.people.includes(l.by)) c.people.push(l.by)
+    c.lines++
+    calls.set(l.call, c)
+  }
+  const picked = all.filter((l) => (!call || l.call === call) && (!since || l.ts > since))
+  const n = Math.max(1, Math.min(1000, Number(limit) || 200))
+  return { lines: picked.slice(-n), more: picked.length > n, calls: [...calls.values()].sort((a, b) => a.start - b.start) }
+}
+
+/** Transcript lines as plain text for an agent: one per line, with who and when. */
+export function renderLines ({ lines, more, calls }, { tz } = {}) {
+  if (!lines.length) return calls.length ? 'No transcript lines match.' : 'Nothing has been transcribed in this session yet.'
+  const time = (ts) => new Date(ts).toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit', ...(tz ? { timeZone: tz } : {}) })
+  const out = []
+  if (more) out.push('(older lines left out; ask with since or call for them)')
+  let call = ''
+  for (const l of lines) {
+    if (l.call !== call) {
+      call = l.call
+      const c = calls.find((x) => x.call === call)
+      out.push(`Call ${call}${c ? ` (${new Date(c.start).toISOString().slice(0, 16).replace('T', ' ')} UTC, ${c.people.join(', ')})` : ''}:`)
+    }
+    out.push(`- ${time(l.ts)} ${l.by}: ${l.text}`)
+  }
+  return out.join('\n')
+}
+
+/**
+ * The call as one app sees it: our presence client id, whether we're in, and everyone else in
+ * voice with the signal they left for us (only ours: everyone's travels, each reads its own).
+ */
+export function voiceView ({ awareness, clientID, members = [], doc }) {
+  const me = cleanVoice(awareness.getLocalState()?.voice)
+  const peers = []
+  for (const [id, s] of awareness.getStates()) {
+    if (id === clientID || !s || !s.name) continue
+    const v = cleanVoice(s.voice)
+    if (!v) continue
+    peers.push({ id, name: s.name, color: s.color || '', muted: v.muted, since: v.since, call: v.call, ...(v.transcribing ? { transcribing: true } : {}), signal: v.sig[String(clientID)] || null })
+  }
+  peers.sort((a, b) => a.since - b.since || a.id - b.id)
+  const t = doc ? transcribeSetting(doc, members) : { on: false }
+  const call = me ? me.call : (peers[0] ? peers[0].call : '')
+  // When the call began: its first person in. The chat shows it, and the calls before it.
+  const starts = [...(me ? [me.since] : []), ...peers.map((p) => p.since)].filter((x) => x > 0)
+  const said = doc ? readLines(doc, { limit: 1 }) : { calls: [] }
+  return {
+    me: clientID,
+    in: !!me,
+    muted: !!(me && me.muted),
+    call,
+    since: starts.length ? Math.min(...starts) : 0,
+    transcribe: t.on,
+    peers,
+    // The latest lines of the call going on now, as each is written down.
+    recent: doc && call ? readLines(doc, { call, limit: RECENT }).lines : [],
+    // Every call that has a transcript: when, who spoke, how many lines.
+    calls: said.calls
+  }
+}
+
+/** Who is in voice, for status: name -> { muted, transcribing }. */
+export function inVoice (awareness, clientID) {
+  const out = new Map()
+  for (const [id, s] of awareness.getStates()) {
+    const v = s && s.name ? cleanVoice(s.voice) : null
+    if (v) out.set(s.name, { muted: v.muted, ...(v.transcribing ? { transcribing: true } : {}), ...(id === clientID ? { me: true } : {}) })
+  }
+  return out
+}
+
+export const TRANSCRIPT_DESCRIPTION = 'Read what people said in the session\'s voice calls: the transcript lines, oldest first, with who said what and when. ' +
+  'People talk in calls in the Quilt app; while the session owner has transcripts on, each person who agreed has their own speech written here. ' +
+  'quilt_status says who is in a call now. Read the latest call before acting on something decided out loud, and ask in chat when a line is unclear.'
+
+/** Who is in a call, for an agent's status: a heading and a line each, or nothing when nobody is. */
+export function voiceStatusLines (people, transcribe) {
+  if (!people.length) return []
+  return [
+    `## In a voice call${transcribe ? ' (transcribed: quilt_voice_transcript reads it)' : ' (not transcribed: ask in chat what was decided)'}`,
+    ...people.map((p) => `- ${p.name}${p.muted ? ' (muted)' : ''}${transcribe && !p.transcribing ? ' (not transcribed)' : ''}`)
+  ]
+}

package/src/wake-tool.js

@@ -0,0 +1,76 @@
+// quilt_wake (plans/agent-wake.md): step 2 of joining, the same in a folder (mcp.js, through the
+// app's control API) and hosted (relay-mcp.js). The agent picks how Quilt wakes it; the tool sets
+// that way up where it runs (the relay's webhook or email subscription, the folder's --on-mention
+// command), switches the others off so the agent is never woken twice, and records the choice with
+// the accounts API so people can see it.
+import { z } from 'zod'
+import { WAKE_METHODS, describeWake, wakeLabel } from './wake.js'
+import { describeSubscription } from './webhooks.js'
+
+export const WAKE_DESCRIPTION = 'Step 2 of joining Quilt: choose how Quilt wakes you when you are mentioned, sent a direct message, handed a task or sent email. ' +
+  'With no method: the ways that fit you and what you chose. With method: sets it up and records it (people see how each agent wakes). ' +
+  'webhook takes url (secret, bearer optional); email takes address, then code from the email Quilt sends; command takes command (on a computer running quilt join); schedule takes every_minutes.'
+
+export const WAKE_INPUT = {
+  method: z.enum(WAKE_METHODS).optional().describe('How Quilt wakes you; leave out to see the ways that fit you'),
+  url: z.string().max(2000).optional().describe('webhook: the public https URL Quilt POSTs to'),
+  secret: z.string().max(200).optional().describe('webhook: signing secret (Quilt makes one when left out)'),
+  bearer: z.string().max(500).optional().describe('webhook: a key your receiver wants as Authorization: Bearer'),
+  address: z.string().max(254).optional().describe('email: the inbox you watch'),
+  code: z.string().max(12).optional().describe('email: the code Quilt emailed to that address'),
+  command: z.string().max(2000).optional().describe('command: what to run on each event (the event JSON on stdin)'),
+  every_minutes: z.number().int().min(1).max(1440).optional().describe('schedule: how often you check quilt_inbox')
+}
+
+/**
+ * Runs quilt_wake. `api(method, route, body)` reaches the accounts API as the agent; `relay` sets
+ * the relay's one subscription ({ subscribe(given) → what the agent is shown, unsubscribe() });
+ * `onMention(command)` sets or (with '') clears a folder's --on-mention command (null when hosted).
+ */
+export async function runWakeTool (args, { api, relay, onMention = null }) {
+  const method = args.method
+  if (!method) {
+    const r = await api('GET', '/v1/agents/me/wake')
+    return describeWake({ ...r.wake, pending: r.wake.pending }, r.ways)
+  }
+  const record = (body) => api('PUT', '/v1/agents/me/wake', { method, ...body })
+  const offElsewhere = async ({ keepRelay = false, keepCommand = false } = {}) => {
+    if (!keepRelay) await relay.unsubscribe().catch(() => {})
+    if (!keepCommand && onMention) await onMention('')
+  }
+  if (method === 'email') {
+    if (args.code !== undefined) {
+      const r = await record({ code: args.code })
+      await relay.subscribe({ email: true })
+      await offElsewhere({ keepRelay: true })
+      return `Quilt wakes you by email now: each event goes to ${r.wake.detail.address} (a few at once come as one email), from the session's own address. Recorded: ${r.wake.label}.`
+    }
+    const r = await record({ address: args.address })
+    return `Quilt emailed a code to ${r.wake.pending.address}. Give it back with quilt_wake { method: "email", code: "<the code>" } within 30 minutes; nothing else is sent there until you do.`
+  }
+  if (method === 'webhook') {
+    // Checked by the accounts API first (does a webhook fit you, is the URL one Quilt may POST to), then set up.
+    await record({ url: args.url })
+    const shown = await relay.subscribe({ url: args.url, secret: args.secret, bearer: args.bearer })
+    await offElsewhere({ keepRelay: true })
+    return `${describeSubscription(shown, { showSecret: !!shown.made })}\nRecorded: wakes by webhook.`
+  }
+  if (method === 'command') {
+    if (!onMention) throw new Error('command is for an agent on a computer running `quilt join`: choose webhook, email or schedule.')
+    if (!String(args.command || '').trim()) throw new Error('command: what to run on each event.')
+    const r = await record({})
+    await onMention(String(args.command))
+    await offElsewhere({ keepCommand: true })
+    return `Quilt runs \`${args.command}\` on each event now (the event JSON on stdin and in QUILT_EVENT, one at a time). Recorded: ${r.wake.label}.`
+  }
+  const r = await record(method === 'schedule' ? { every_minutes: args.every_minutes } : {})
+  await offElsewhere()
+  const how = {
+    wait: 'Loop on `quilt inbox --wait --json`: it returns as soon as something is for you.',
+    push: 'Subscribe to the quilt://inbox resource (Claude Code: start it with the quilt channel); you are told as each event arrives.',
+    schedule: `Check quilt_inbox every ${r.wake.detail.everyMinutes} minutes; people see that you may take that long to answer.`,
+    turns: 'You are woken when your person starts a turn; `npx heyquilt sync` shows what waited.',
+    none: 'Quilt won\'t wake you: what is for you waits in quilt_inbox until your person starts you.'
+  }[method]
+  return `${how} Recorded: ${wakeLabel(r.wake)}.`
+}

package/src/wake.js

@@ -0,0 +1,79 @@
+// How Quilt wakes an agent (plans/agent-wake.md): step 2 of joining. The ways, in words for agents
+// and for the people who need to know whether an @mention reaches one. Pure: no I/O.
+
+export const WAKE_METHODS = ['webhook', 'email', 'command', 'wait', 'push', 'schedule', 'turns', 'none']
+
+// What each way is, who it fits, and how to choose it with quilt_wake.
+const WAYS = {
+  webhook: { fits: 'any agent with a public https URL', what: 'Quilt POSTs each event (mention, direct message, task, email) to your URL, signed, as it happens.', how: 'quilt_wake { method: "webhook", url: "https://…", secret?: "…", bearer?: "…" }' },
+  email: { fits: 'any agent with an inbox it watches', what: 'Quilt emails you each event (a few at once come as one email). The address is confirmed with a code first.', how: 'quilt_wake { method: "email", address: "you@example.com" }, then quilt_wake { method: "email", code: "<the code Quilt emailed>" }' },
+  command: { fits: 'agents on a computer running `quilt join`', what: 'Quilt runs your command on each event, the event as JSON on stdin and in QUILT_EVENT.', how: 'quilt_wake { method: "command", command: "<command to run>" } (the same as `quilt join --on-mention`)' },
+  wait: { fits: 'agents on a computer with a loop of their own', what: '`quilt inbox --wait` returns as soon as something is for you; run it again after each one.', how: 'quilt_wake { method: "wait" }, then loop on `quilt inbox --wait --json`' },
+  push: { fits: 'an MCP client that keeps Quilt\'s MCP open and listens', what: 'your client subscribes to the quilt://inbox resource (Claude Code: its quilt channel) and is told as each event arrives.', how: 'quilt_wake { method: "push" }, then subscribe to quilt://inbox' },
+  schedule: { fits: 'agents that run on a timer (cron)', what: 'you check quilt_inbox every few minutes; Quilt tells people how long you may take to answer.', how: 'quilt_wake { method: "schedule", every_minutes: 5 }' },
+  turns: { fits: 'sandboxes wiped after every turn', what: 'you are woken only when your person starts a turn; `npx heyquilt sync` shows what waited.', how: 'quilt_wake { method: "turns" }' },
+  none: { fits: 'agents only their person starts', what: 'Quilt doesn\'t wake you: what is for you waits in quilt_inbox until your person starts you.', how: 'quilt_wake { method: "none" }' }
+}
+
+/** Which ways fit an agent: `cli` (a computer running quilt join), `sandbox`, or neither (over HTTP). */
+export function waysFor ({ cli = false, sandbox = false } = {}) {
+  if (cli) return ['command', 'wait', 'push', 'webhook', 'email', 'schedule', 'none']
+  if (sandbox) return ['webhook', 'email', 'turns', 'schedule', 'none']
+  // Over HTTP: a sandbox's agent reaches Quilt this way too, so turns is offered here as well.
+  return ['webhook', 'email', 'schedule', 'turns', 'none']
+}
+
+/** The ways that fit, as a list an agent can choose from. */
+export function describeWays (ways) {
+  return ways.map((m) => `- ${m}: ${WAYS[m].what} For ${WAYS[m].fits}. ${WAYS[m].how}`).join('\n')
+}
+
+/** How an agent wakes, in a few words for people: "wakes by webhook (hooks.example.com)". */
+export function wakeLabel (wake) {
+  const w = wake || {}
+  const d = w.detail || {}
+  switch (w.method) {
+    case 'webhook': return `wakes by webhook${d.host ? ` (${d.host})` : ''}`
+    case 'email': return 'wakes by email'
+    case 'command': return 'wakes by a command on its computer'
+    case 'wait': return 'waits for events on its computer'
+    case 'push': return 'wakes by MCP push'
+    case 'schedule': return `checks every ${d.everyMinutes || '?'} min`
+    case 'turns': return 'wakes when its person starts a turn'
+    case 'none': return 'not woken: only when its person starts it'
+    default: return "hasn't said how Quilt wakes it"
+  }
+}
+
+/** Step 2, as every agent is told it until it has chosen. */
+export const WAKE_STEP = 'Step 2 of 3: choose how Quilt wakes you when you are mentioned, sent a direct message, handed a task or sent email, so you answer without being checked on. Call quilt_wake to see the ways that fit you and pick one.'
+
+/** The reminder on every answer until the agent has chosen. */
+export const WAKE_REMINDER = 'Quilt can\'t wake you yet: choose how with quilt_wake (step 2 of joining), so people\'s @mentions reach you.'
+
+/** What quilt_wake answers with no arguments: what you chose, and the ways that fit you. */
+export function describeWake (wake, ways) {
+  const chosen = wake && wake.method ? `You chose: ${wake.method} (${wakeLabel(wake)}).` : 'You haven\'t chosen yet.'
+  const pending = wake && wake.pending && wake.pending.address ? ` Waiting for the code sent to ${wake.pending.address}: quilt_wake { method: "email", code: "…" }.` : ''
+  return `${chosen}${pending}\n\nWays Quilt can wake you:\n${describeWays(ways)}\n\nPick the one that fits how you run; you can change it any time.`
+}
+
+/**
+ * Whether to remind an agent of step 2, asking `fetchWake()` (→ { method } or null; throws when it
+ * can't tell) at most every `ttlMs`. `reminder()` is WAKE_REMINDER or ''; `chose(method)` records a
+ * choice at once (quilt_wake). An answer that can't be had reminds nobody.
+ */
+export function wakeCheck ({ fetchWake, ttlMs = 10 * 60 * 1000, now = Date.now } = {}) {
+  let known = null // { method, at }
+  let asking = null
+  return {
+    async reminder () {
+      if (!known || now() - known.at >= ttlMs) {
+        if (!asking) asking = Promise.resolve().then(fetchWake).then((w) => { known = { method: (w && w.method) || null, at: now() } }, () => {}).finally(() => { asking = null })
+        await asking
+      }
+      return known && !known.method ? WAKE_REMINDER : ''
+    },
+    chose (method) { known = { method: method || null, at: now() } }
+  }
+}

package/src/webhook-cli.js

@@ -0,0 +1,62 @@
+// `quilt webhook …` and `quilt join --webhook-url`: a thin command line over the one webhook an
+// agent subscribes with quilt_webhook_subscribe (session.js; the relay keeps and sends it). Keys are
+// read from environment variables by NAME, so they never sit in shell history; neither the bearer
+// key nor a secret you gave is ever printed (a secret Quilt made is, once).
+import { describeSubscription, describeWebhookTest } from './webhooks.js'
+
+export const WEBHOOK_USAGE = `usage:
+  quilt webhook set <url> [--bearer-env VAR] [--secret-env VAR] [--events chat.mention,chat.dm,task.assigned] [--coalesce]
+  quilt webhook clear
+  quilt webhook test
+  quilt webhook [status]`
+
+/** Parses `quilt webhook ...` args: { op, url?, bearerEnv?, secretEnv?, events?, coalesce? }. Throws the usage on a mistake. */
+export function parseWebhookArgs (args) {
+  const a = [...args]
+  const take = (...flags) => {
+    for (const flag of flags) {
+      const i = a.indexOf(flag)
+      if (i === -1) continue
+      const v = a[i + 1]
+      if (!v || v.startsWith('--')) throw new Error(`${flag} needs a value\n${WEBHOOK_USAGE}`)
+      a.splice(i, 2)
+      return v
+    }
+    return undefined
+  }
+  const bearerEnv = take('--bearer-env', '--token-env')
+  const secretEnv = take('--secret-env')
+  const ev = take('--events')
+  const ci = a.indexOf('--coalesce')
+  const coalesce = ci !== -1
+  if (coalesce) a.splice(ci, 1)
+  const sub = a.shift() || 'status'
+  if (sub === 'set') {
+    const url = a.shift()
+    if (!url || a.length) throw new Error(WEBHOOK_USAGE)
+    return { op: 'set', url, ...(bearerEnv ? { bearerEnv } : {}), ...(secretEnv ? { secretEnv } : {}), ...(ev ? { events: ev.split(',').map((x) => x.trim()).filter(Boolean) } : {}), ...(coalesce ? { coalesce: true } : {}) }
+  }
+  if (bearerEnv || secretEnv || ev || coalesce || a.length) throw new Error(WEBHOOK_USAGE)
+  if (sub === 'clear' || sub === 'test') return { op: sub }
+  if (sub === 'status' || sub === 'info') return { op: 'status' }
+  throw new Error(WEBHOOK_USAGE)
+}
+
+/** The value of environment variable `name` (for `flag`), or a readable error that never holds the value. */
+export function fromEnv (name, flag = '--bearer-env', env = process.env) {
+  if (!name) return undefined
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`${flag} takes the NAME of an environment variable, like MY_HOOK_KEY (not the key itself).`)
+  const v = env[name]
+  if (!v) throw new Error(`The environment variable ${name} is empty or not set.`)
+  return v
+}
+
+/** What `quilt webhook status` prints. */
+export function describeStatus (w) {
+  if (!w) return 'No webhook. Set one with `quilt webhook set <https url>` (or quilt_webhook_subscribe).'
+  const by = w.relay ? 'the relay sends it (it reaches you while this computer sleeps)' : 'this computer sends it, while it is awake' + (w.local ? ' (the relay cannot reach that URL)' : ' (the relay takes it over once this folder is let in)')
+  const last = w.last ? `; last POST ${w.last.ok ? 'ok' : 'failed'}${w.last.status ? ` (HTTP ${w.last.status})` : ''}${w.last.error ? `: ${w.last.error}` : ''} at ${new Date(w.last.at).toISOString()}` : ''
+  return `Webhook: ${w.url} on ${w.events.join(', ')}${w.bearer ? ', bearer key: set' : ''}${w.coalesce ? ', bursts coalesced' : ''}; ${by}${last}.`
+}
+
+export { describeSubscription, describeWebhookTest }

package/src/webhooks.js

@@ -11,12 +11,13 @@
 // The pure parts (shapes, signing, validation) are shared by the relay, which
 // delivers for hosted agents, and the local session, which delivers for agents
 // joined from a computer.
+import { authorOf } from './ui/chat.js'
 import crypto from 'node:crypto'
 import dns from 'node:dns'
 import net from 'node:net'
 
-export const WEBHOOK_EVENTS = ['chat.mention', 'chat.dm', 'task.assigned']
-export const EVENT_OF_KIND = { mention: 'chat.mention', dm: 'chat.dm', task: 'task.assigned' }
+export const WEBHOOK_EVENTS = ['chat.mention', 'chat.dm', 'task.assigned', 'email.received']
+export const EVENT_OF_KIND = { mention: 'chat.mention', dm: 'chat.dm', task: 'task.assigned', email: 'email.received' }
 export const MAX_URL = 2000
 export const MAX_SECRET = 200
 export const MIN_SECRET = 16
@@ -122,7 +123,7 @@ export const newSecret = () => crypto.randomBytes(24).toString('hex')
  * agent chose is kept (16 to 200 characters); without one, a new one is made and the
  * agent is shown it once, in the tool's answer.
  */
-export function makeSubscription ({ url, secret, events, bearer } = {}, { allowLocal = false, now = Date.now } = {}) {
+export function makeSubscription ({ url, secret, events, bearer, coalesce } = {}, { allowLocal = false, now = Date.now } = {}) {
   const u = parseWebhookUrl(url, { allowLocal })
   const ev = parseWebhookEvents(events)
   let s = secret == null ? '' : String(secret)
@@ -132,17 +133,17 @@ export function makeSubscription ({ url, secret, events, bearer } = {}, { allowL
   // A key the receiver wants on every POST (a Grok Bot routine's sender key, for example), sent as Authorization: Bearer <key>.
   const b = bearer == null ? '' : String(bearer).trim()
   if (b.length > MAX_BEARER || /[\r\n]/.test(b)) throw new Error(`The bearer key must be one line of at most ${MAX_BEARER} characters.`)
-  return { url: u, secret: s, events: ev, since: now(), made, ...(b ? { bearer: b } : {}) }
+  return { url: u, secret: s, events: ev, since: now(), made, ...(b ? { bearer: b } : {}), ...(coalesce ? { coalesce: true } : {}) }
 }
 
 /** The subscription as an agent sees it (its secret only when it was just made). */
 export function describeSubscription (sub, { showSecret = false } = {}) {
   if (!sub) return 'No webhook: Quilt only answers quilt_inbox when you ask.'
-  const lines = [`Webhook: Quilt POSTs to ${sub.url} on ${sub.events.join(', ')}${sub.bearer ? ', with your bearer key in the Authorization header' : ''}.`]
+  const lines = [`Webhook: Quilt POSTs to ${sub.url} on ${sub.events.join(', ')}${sub.bearer ? ', with your bearer key in the Authorization header' : ''}${sub.coalesce ? ', a burst in one POST (its events in `events`)' : ''}${sub.local ? ' (sent from this computer: the relay cannot reach that URL)' : ''}.`]
   if (showSecret) lines.push(`Secret (shown once; check x-quilt-signature with it): ${sub.secret}`)
-  lines.push('Each POST is JSON ({ event, id, session, workspace, room, to, by, text, ts, task?, context? }; session: the session it is from, which you name as `session` in the tools you answer with, so an answer never lands in another session; workspace: { id } or null; context: the messages before this one between you and its sender, oldest first) with x-quilt-event, x-quilt-delivery, x-quilt-timestamp and ' +
+  lines.push('Each POST is JSON ({ event, id, session, workspace, room, to, by, text, ts, task?, mail?, context? }; session: the session it is from, which you name as `session` in the tools you answer with, so an answer never lands in another session; workspace: { id } or null; mail: { id } of an email to the session, read with quilt_mail; context: the messages before this one between you and its sender, oldest first) with x-quilt-event, x-quilt-delivery, x-quilt-timestamp and ' +
     'x-quilt-signature: sha256=HMAC-SHA256(secret, "<timestamp>.<body>"). Answer 2xx quickly; a failed POST is retried a few times. ' +
-    'What you are told is still in quilt_inbox. Stop with quilt_webhook_unsubscribe.')
+    'What you are told is still in quilt_inbox. quilt_webhook_test POSTs a webhook.test event now; stop with quilt_webhook_unsubscribe.')
   return lines.join('\n')
 }
 
@@ -153,12 +154,13 @@ export function describeSubscription (sub, { showSecret = false } = {}) {
 export function webhookPayload (e, { room = '', to = '', workspace = '' } = {}) {
   const p = { event: EVENT_OF_KIND[e.kind] || e.kind, id: String(e.id || ''), room, session: room, workspace: workspace ? { id: String(workspace) } : null, to, by: String(e.by || ''), text: String(e.text || ''), ts: Number(e.ts) || Date.now() }
   if (e.kind === 'task' && e.task) p.task = { id: e.task.id, title: e.task.title, column: e.task.column, assignee: e.task.assignee ?? null, forAi: !!e.task.forAi, tool: e.task.tool || '', files: e.task.files || [] }
+  if (e.kind === 'email' && e.mail) p.mail = { id: String(e.mail) } // read it with quilt_mail (read: id)
   if (e.commit) p.commit = true // work this member asked to commit was committed: nothing to answer
   if (e.nudge) p.nudge = true // a reminder from Quilt (uncommitted work): nothing to answer
   // The conversation before this with whoever it is from (conversation.js), so an agent woken
   // fresh knows what "that" refers to; `earlier` older messages are a quilt_conversation away.
   if (Array.isArray(e.context) && e.context.length) {
-    p.context = e.context.map((m) => ({ id: m.id, by: m.by, ...(m.to ? { to: m.to } : {}), text: m.text, ts: m.ts }))
+    p.context = e.context.map((m) => ({ id: m.id, by: authorOf(m), ...(m.to ? { to: m.to } : {}), text: m.text, ts: m.ts }))
     if (e.earlier) p.earlier = e.earlier
   }
   return p
@@ -184,7 +186,7 @@ const retryable = (status) => status === 408 || status === 429 || status >= 500
  * the receiver is down, slow or answers 5xx/429. Resolves { ok, status, attempts, error? };
  * never throws. `fetch`, `delays` and `sleep` are for tests.
  */
-export async function deliverWebhook (sub, payload, { fetch = globalThis.fetch, delays = RETRY_DELAYS_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), timeoutMs = DELIVERY_TIMEOUT_MS, now = Date.now, log = () => {} } = {}) {
+export async function deliverWebhook (sub, payload, { fetch = globalThis.fetch, delays = RETRY_DELAYS_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), timeoutMs = DELIVERY_TIMEOUT_MS, now = Date.now, log = () => {}, checkHost = null } = {}) {
   const body = JSON.stringify(payload)
   const delivery = crypto.randomUUID()
   let status = 0
@@ -192,6 +194,11 @@ export async function deliverWebhook (sub, payload, { fetch = globalThis.fetch,
   let attempt = 0
   while (attempt < delays.length + 1) {
     attempt++
+    // From Quilt's servers, the host must still be public as it resolves now (DNS can change): never retried.
+    if (checkHost) {
+      const host = await checkHost(sub.url)
+      if (!host.ok) { log(`webhook to ${sub.url} skipped (${payload.event}): ${host.reason}`); return { ok: false, status: 0, attempts: attempt, error: host.reason, delivery } }
+    }
     const ts = String(now())
     try {
       const res = await fetch(sub.url, {
@@ -233,3 +240,12 @@ export async function deliverEvents (sub, events, { room = '', to = '', workspac
   }
   return out
 }
+
+/** For quilt_webhook_subscribe's `coalesce`. */
+export const COALESCE_HELP = 'true: a burst wakes you once. Events are gathered for 2 s, and any that follow within 30 s of a POST go together in one more POST; a POST with several has them all, oldest first, in `events` (the first one\'s fields on top). Default false: one POST per event.'
+
+/** What quilt_webhook_test (and `quilt webhook test`) says. */
+export function describeWebhookTest (r) {
+  if (r && r.ok) return `Test POST delivered: your receiver answered HTTP ${r.status}.`
+  return `Test POST failed${r && r.status ? ` (HTTP ${r.status})` : ''}${r && r.attempts ? ` after ${r.attempts} tr${r.attempts === 1 ? 'y' : 'ies'}` : ''}: ${(r && r.error) || 'no answer'}.`
+}