heyquilt 0.0.1 → 0.3.90

package/src/api/github-app.js

@@ -0,0 +1,172 @@
+// Quilt's GitHub App ("Quilt by heyquilt"): a person connects their GitHub account once, installs
+// the app on the repositories they choose, and from then on the relay commits agents' work there
+// (relay-commit.js) with short-lived credentials made for one repository at a time. Nobody creates
+// or pastes a token, and nobody needs to be online.
+//
+// The app's private key lives only on this API. The relay asks for a repository's credentials
+// for a session's owner (routes/github.js); they are given only when the owner's GitHub account
+// may write to that repository, so a session can't point agents at a repository its owner can't
+// push to just because the app is installed there.
+//
+// GitHub is the first host. The relay only sees { token, expiresAt } for a repository, so other
+// hosts (GitLab, Bitbucket, Azure DevOps, Gitea) can be added the same way.
+import crypto from 'node:crypto'
+
+const API = 'https://api.github.com'
+export const WRITE_ROLES = ['admin', 'maintain', 'write']
+export const READ_ROLES = [...WRITE_ROLES, 'triage', 'read']
+// What the relay's credentials may do: commit (contents, workflow files), open and merge pull
+// requests and read checks (write); or fetch and clone (read: a folder's git, for agents).
+export const COMMIT_PERMISSIONS = { contents: 'write', pull_requests: 'write', workflows: 'write', checks: 'read', statuses: 'read', metadata: 'read' }
+export const READ_PERMISSIONS = { contents: 'read', metadata: 'read' }
+
+const b64url = (buf) => Buffer.from(buf).toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_')
+
+/** The app's settings from the environment, or null when it isn't set up. The key may be base64 of the PEM. */
+export function appConfig (env = process.env) {
+  const id = String(env.GITHUB_APP_ID || '').trim()
+  let key = String(env.GITHUB_APP_PRIVATE_KEY || '').trim()
+  if (key && !key.includes('BEGIN')) { try { key = Buffer.from(key, 'base64').toString('utf8') } catch { key = '' } }
+  const cfg = { id, key, slug: String(env.GITHUB_APP_SLUG || '').trim(), clientId: String(env.GITHUB_APP_CLIENT_ID || '').trim(), clientSecret: String(env.GITHUB_APP_CLIENT_SECRET || '').trim(), webhookSecret: String(env.GITHUB_APP_WEBHOOK_SECRET || '').trim() }
+  return cfg.id && cfg.key.includes('PRIVATE KEY') && cfg.slug && cfg.clientId && cfg.clientSecret ? cfg : null
+}
+
+/** The app's own sign-in (a JWT, ten minutes at most), for asking GitHub about installations. */
+export function appJwt (cfg, now = Date.now()) {
+  const iat = Math.floor(now / 1000) - 60 // GitHub's clock may be a little behind
+  const head = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))
+  const body = b64url(JSON.stringify({ iat, exp: iat + 9 * 60, iss: cfg.id }))
+  const sig = crypto.sign('RSA-SHA256', Buffer.from(`${head}.${body}`), cfg.key)
+  return `${head}.${body}.${b64url(sig)}`
+}
+
+/** A link's `state`: who started connecting (signed, for ten minutes), so the callback knows whose account it is. */
+export function signState (cfg, userId, now = Date.now(), { scope = '', scopeId = '' } = {}) {
+  // A connection for a workspace or an org carries its scope (w or o) and id along with the person.
+  const who = scope && scopeId ? `${userId}~${scope === 'workspace' ? 'w' : 'o'}${scopeId}` : userId
+  const payload = `${who}.${now + 10 * 60 * 1000}`
+  const mac = crypto.createHmac('sha256', cfg.clientSecret).update(payload).digest('hex').slice(0, 32)
+  return `${payload}.${mac}`
+}
+
+/** What a state made by signState says: { userId, scope?, scopeId? }, or null (forged, or older than ten minutes). */
+export function readStateFull (cfg, state, now = Date.now()) {
+  const m = /^([A-Za-z0-9_-]{1,64})(?:~([wo])([0-9a-f-]{36}))?\.(\d{1,16})\.([0-9a-f]{32})$/.exec(String(state || ''))
+  if (!m) return null
+  const who = m[2] ? `${m[1]}~${m[2]}${m[3]}` : m[1]
+  const want = crypto.createHmac('sha256', cfg.clientSecret).update(`${who}.${m[4]}`).digest('hex').slice(0, 32)
+  if (!crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[5]))) return null
+  if (Number(m[4]) < now) return null
+  return { userId: m[1], ...(m[2] ? { scope: m[2] === 'w' ? 'workspace' : 'org', scopeId: m[3] } : {}) }
+}
+
+/** The user id in a state made by signState, or null (forged, or older than ten minutes). */
+export function readState (cfg, state, now = Date.now()) {
+  const r = readStateFull(cfg, state, now)
+  return r ? r.userId : null
+}
+
+export class GitHubAppError extends Error {
+  constructor (status, message) { super(message); this.status = status }
+}
+
+/** The calls the API makes to GitHub for the app. `fetch` is for tests. */
+export function githubApp (cfg, { fetch = globalThis.fetch, now = Date.now } = {}) {
+  const accountIds = new Map() // login -> { id, at }
+  const call = async (method, url, { auth, body, form } = {}) => {
+    const res = await fetch(url.startsWith('http') ? url : `${API}${url}`, {
+      method,
+      headers: { 'user-agent': 'quilt-api', accept: 'application/json', 'x-github-api-version': '2022-11-28', ...(auth ? { authorization: auth } : {}), ...(body || form ? { 'content-type': 'application/json' } : {}) },
+      ...(body || form ? { body: JSON.stringify(body || form) } : {})
+    })
+    let json = null
+    try { json = await res.json() } catch {}
+    if (!res.ok) throw new GitHubAppError(res.status, (json && json.message) || `GitHub answered ${res.status}`)
+    return json
+  }
+  const asApp = () => `Bearer ${appJwt(cfg, now())}`
+  return {
+    /** The link that installs the app (or changes which repositories it has), carrying `state`; `targetId` goes straight to that account's install page. */
+    installUrl: (state, { targetId = null } = {}) => targetId
+      ? `https://github.com/apps/${cfg.slug}/installations/new/permissions?target_id=${encodeURIComponent(targetId)}&state=${encodeURIComponent(state)}`
+      : `https://github.com/apps/${cfg.slug}/installations/new?state=${encodeURIComponent(state)}`,
+    /** A GitHub account's (person's or organization's) id, from its public profile; remembered for a day. */
+    async accountId (login) {
+      const hit = accountIds.get(login.toLowerCase())
+      if (hit && now() - hit.at < 24 * 60 * 60 * 1000) return hit.id
+      const u = await call('GET', `/users/${encodeURIComponent(login)}`)
+      const id = Number(u && u.id) || null
+      if (id) accountIds.set(login.toLowerCase(), { id, at: now() })
+      return id
+    },
+    /** Who signed in on GitHub: the code from the callback, exchanged and asked. { id, login }. */
+    async whoAuthorized (code) {
+      const t = await call('POST', 'https://github.com/login/oauth/access_token', { form: { client_id: cfg.clientId, client_secret: cfg.clientSecret, code } })
+      if (!t || !t.access_token) throw new GitHubAppError(400, (t && (t.error_description || t.error)) || 'GitHub did not sign you in')
+      const u = await call('GET', '/user', { auth: `Bearer ${t.access_token}` })
+      return { id: Number(u.id), login: String(u.login) }
+    },
+    /** The app's installation on owner/name, or null when it isn't installed there. */
+    async installation (owner, name) {
+      try { return (await call('GET', `/repos/${owner}/${name}/installation`, { auth: asApp() })).id } catch (err) { if (err.status === 404) return null; throw err }
+    },
+    /** Credentials for one repository of an installation, for about an hour: { token, expiresAt }. */
+    async repoToken (installationId, name, { access = 'write' } = {}) {
+      const r = await call('POST', `/app/installations/${installationId}/access_tokens`, { auth: asApp(), body: { repositories: [name], permissions: access === 'read' ? READ_PERMISSIONS : COMMIT_PERMISSIONS } })
+      return { token: r.token, expiresAt: Date.parse(r.expires_at) || now() + 50 * 60 * 1000 }
+    },
+    /** Sets the app's webhook to deliver JSON signed with `secret` (PATCH /app/hook/config, as the app). Idempotent. */
+    async setWebhookSecret (secret) {
+      await call('PATCH', '/app/hook/config', { auth: asApp(), body: { content_type: 'json', secret } })
+    },
+    /** The app's recent webhook deliveries that failed and were not delivered again yet: [{ id }]. */
+    async failedDeliveries () {
+      const list = await call('GET', '/app/hook/deliveries?per_page=100', { auth: asApp() })
+      return (Array.isArray(list) ? list : []).filter((d) => d && Number.isInteger(d.id) && !d.redelivery && (d.status_code >= 400 || d.status_code === 0 || (d.status && d.status !== 'OK'))).map((d) => ({ id: d.id }))
+    },
+    /** Asks GitHub to deliver webhook `id` again. */
+    async redeliver (id) { await call('POST', `/app/hook/deliveries/${Number(id)}/attempts`, { auth: asApp() }) },
+    /** What `login` may do in owner/name ('admin', 'maintain', 'write', 'triage', 'read' or 'none'), asked with `token`. */
+    async role (token, owner, name, login) {
+      try {
+        const r = await call('GET', `/repos/${owner}/${name}/collaborators/${encodeURIComponent(login)}/permission`, { auth: `Bearer ${token}` })
+        return String((r && (r.role_name || r.permission)) || 'none')
+      } catch (err) { if (err.status === 404 || err.status === 403) return 'none'; throw err }
+    }
+  }
+}
+
+/**
+ * The webhook secret the API verifies GitHub's events with, set on the app by the API itself at
+ * start (PATCH /app/hook/config): the one from the environment when given, else one made once and
+ * kept in the store (`github_webhook_secret`), so nobody pastes a secret into GitHub's settings.
+ * `hook.value` is where the route reads it. Resolves the secret, or '' when the app isn't set up.
+ */
+export async function ensureWebhookSecret ({ cfg, app, store, hook, log = () => {} }) {
+  if (!cfg || !app) return ''
+  let secret = cfg.webhookSecret || ''
+  if (!secret && store && store.getSetting) {
+    secret = (await store.getSetting('github_webhook_secret')) || ''
+    if (!secret) {
+      // Two API machines starting at once each make one: the first stored is the one both use.
+      const made = crypto.randomBytes(32).toString('base64url')
+      if (store.setSettingIfAbsent) secret = await store.setSettingIfAbsent('github_webhook_secret', made)
+      else { await store.setSetting('github_webhook_secret', made); secret = made }
+    }
+  }
+  if (!secret) return ''
+  hook.value = secret
+  try { await app.setWebhookSecret(secret) } catch (err) { log(`github: could not set the app's webhook secret: ${err.message}`) }
+  return secret
+}
+
+/** At start: GitHub delivers again every recent webhook that failed to reach us (a deploy, an outage). How many were asked for. */
+export async function redeliverFailed ({ app, log = () => {} }) {
+  if (!app) return 0
+  let n = 0
+  try {
+    for (const d of await app.failedDeliveries()) { try { await app.redeliver(d.id); n++ } catch (err) { log(`github: could not ask for webhook ${d.id} again: ${err.message}`) } }
+  } catch (err) { log(`github: could not list webhook deliveries: ${err.message}`) }
+  if (n) log(`github: asked for ${n} failed webhook delivery(ies) again`)
+  return n
+}

package/src/api/http.js

@@ -0,0 +1,34 @@
+// Small pieces every API route module shares.
+export class HttpError extends Error { constructor (status, message) { super(message); this.status = status } }
+
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** Ids are uuids; anything else can't exist (and Postgres would reject it), so it's a 404. */
+export function needId (id, what = 'thing') {
+  if (!UUID.test(String(id || ''))) throw new HttpError(404, `no such ${what}`)
+  return String(id)
+}
+
+// C0/C1 controls, zero-width characters (including the byte-order mark), and
+// bidi overrides/isolates: none of these belong in a name, and a bidi override
+// can make a name display backwards or hide characters, e.g. in an email subject.
+const INVISIBLE = /[\u0000-\u001f\u007f-\u009f​-‏‪-‮⁠⁦-⁩؜]/
+
+/** The code points of `value` with control/zero-width/bidi characters removed. */
+export function stripInvisible (value) {
+  return Array.from(String(value ?? '')).filter((ch) => !INVISIBLE.test(ch))
+}
+
+/** A trimmed name with no control characters (it may end up in an email subject).
+ * Slices by code point, not UTF-16 unit, so cutting at `max` never splits a
+ * surrogate pair (e.g. an emoji) into two lone, invalid surrogates. */
+export function cleanName (value, max, message) {
+  const s = stripInvisible(value).slice(0, max).join('').trim()
+  if (!s) throw new HttpError(400, message)
+  return s
+}
+
+/** A non-JSON reply, e.g. the plain-text join instructions an AI reads. */
+export class Raw {
+  constructor (status, body, type = 'text/markdown; charset=utf-8') { this.status = status; this.body = body; this.type = type }
+}

package/src/api/invite-email.js

@@ -0,0 +1,53 @@
+// The emails the accounts API sends itself: org, session and workspace invites.
+export function inviteEmail ({ orgName, inviterName, roleName, link }) {
+  const who = inviterName || 'Someone'
+  return {
+    subject: `${who} invited you to ${orgName} on Quilt`,
+    text: [
+      `${who} invited you to join ${orgName} on Quilt as ${roleName}.`,
+      '',
+      `Accept the invite: ${link}`,
+      '',
+      'Sign in, or create your account, with this email address. The link works for 7 days.',
+      "If you weren't expecting this, you can ignore this email."
+    ].join('\n')
+  }
+}
+
+// Every invite comes from the API's one sender (SMTP_FROM, e.g. "Quilt <hello@heyquilt.com>"): the mailer fills it in.
+
+/** An invite to one session. `link` is the session's join link (it holds the room secret); `site` is heyquilt.com. */
+export function sessionInviteEmail ({ inviterName, sessionName, link, site }) {
+  const who = inviterName || 'Someone'
+  return {
+    subject: `${who} invited you to ${sessionName} on Quilt`,
+    text: [
+      `${who} invited you to ${sessionName}, a live Quilt session where people and their AIs build one project together.`,
+      '',
+      `Join the session: ${link}`,
+      '',
+      'This invite expires in 7 days.',
+      '',
+      `New to Quilt? Download the app from ${site}, sign in with this email address, then open the link again.`,
+      "If you weren't expecting this, you can ignore this email."
+    ].join('\n')
+  }
+}
+
+/** An invite to a workspace. It is accepted in Quilt: the app's home, or `site`/dashboard. */
+export function workspaceInviteEmail ({ inviterName, workspaceName, access, site }) {
+  const who = inviterName || 'Someone'
+  return {
+    subject: `${who} invited you to the ${workspaceName} workspace on Quilt`,
+    text: [
+      `${who} invited you to ${workspaceName}, a Quilt workspace: its sessions, files and people in one place. You would ${access === 'view' ? 'be able to view it' : 'be able to edit it'}.`,
+      '',
+      `Accept it in the Quilt app, or at ${site}/dashboard`,
+      '',
+      'This invite expires in 7 days.',
+      '',
+      `New to Quilt? Create your account at ${site}/signup with this email address and the invite will be waiting for you.`,
+      "If you weren't expecting this, you can ignore this email."
+    ].join('\n')
+  }
+}

package/src/api/issues.js

@@ -0,0 +1,110 @@
+// What an issue report looks like, and how two reports of the same problem end up
+// in one issue: shared by the /v1/issues route, the API's own error recording and
+// both stores, so the memory store (the tested reference) and Postgres agree.
+import crypto from 'node:crypto'
+import { HttpError, UUID, stripInvisible } from './http.js'
+
+export const SURFACES = ['app', 'api', 'web']
+export const KINDS = ['action', 'error', 'http404', 'crash']
+export const OUTCOMES = ['ok', 'slow', 'error']
+export const MAX_BATCH = 20
+const DAY = 24 * 60 * 60 * 1000
+const MAX_CONTEXT_KEYS = 16
+const MAX_CONTEXT_BYTES = 2048
+
+const cut = (value, max) => stripInvisible(value).slice(0, max).join('').trim()
+
+/** A message with the parts that differ between repeats of one problem replaced. */
+export function normalizeMessage (message) {
+  return String(message ?? '').toLowerCase()
+    .replace(/(["'`])(?:(?!\1).){1,500}\1/g, '<str>')
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, '<id>')
+    .replace(/\b[0-9a-f]{8,}\b/g, '<hex>')
+    .replace(/(?:~|[a-z]:\\|\/)[^\s'"`:,()]*[\\/][^\s'"`:,()]*/g, '<path>')
+    .replace(/\d+(\.\d+)?/g, '<n>')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 200)
+}
+
+/** The same problem on the same surface, kind and name always gets this fingerprint. */
+export function fingerprint ({ surface, kind, name, message }) {
+  return crypto.createHash('sha256').update([surface, kind, name, normalizeMessage(message)].join('|')).digest('hex')
+}
+
+/** Context is a few flat facts (which editor, which route): scalars only, bounded. Never throws. */
+export function cleanContext (value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  const out = {}
+  for (const [k, v] of Object.entries(value)) {
+    if (Object.keys(out).length >= MAX_CONTEXT_KEYS) break
+    const key = cut(k, 40)
+    if (!key) continue
+    if (typeof v === 'string') out[key] = cut(v, 200)
+    else if (typeof v === 'number' && Number.isFinite(v)) out[key] = v
+    else if (typeof v === 'boolean') out[key] = v
+  }
+  // Still too big (16 long strings): drop fields from the end until it fits.
+  while (JSON.stringify(out).length > MAX_CONTEXT_BYTES) delete out[Object.keys(out).pop()]
+  return out
+}
+
+const oneOf = (list, value, what) => {
+  const v = String(value ?? '')
+  if (!list.includes(v)) throw new HttpError(400, `${what} must be one of ${list.join(', ')}`)
+  return v
+}
+// Postgres's `integer` column can't hold more than this; a value outside it would turn a
+// whole batch into a 500 (22003). Clamping to null here keeps a bad report a 400, never a crash.
+const INT_MAX = 2_147_483_647
+const intOrNull = (v) => {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return null
+  const n = Math.round(v)
+  return n >= 0 && n <= INT_MAX ? n : null
+}
+
+/**
+ * One event as the stores take it. `surface`, `appVersion`, `platform`, `userId` and
+ * `deviceId` are decided by the caller (the route knows who is reporting), never by the body.
+ */
+export function cleanEvent (raw, { surface, appVersion = '', platform = '', userId = null, deviceId = null, now = Date.now }) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new HttpError(400, 'each event must be an object')
+  const kind = oneOf(KINDS, raw.kind, 'kind')
+  const outcome = oneOf(OUTCOMES, raw.outcome ?? 'ok', 'outcome')
+  const name = cut(raw.name, 80)
+  if (!name) throw new HttpError(400, 'name is empty')
+  const t = now()
+  const at = typeof raw.occurredAt === 'number' ? raw.occurredAt : Date.parse(raw.occurredAt)
+  const occurredAt = Number.isFinite(at) ? Math.min(Math.max(at, t - DAY), t + DAY) : t
+  const message = cut(raw.message, 500)
+  const e = {
+    surface: oneOf(SURFACES, surface, 'surface'),
+    kind, name, outcome,
+    status: intOrNull(raw.status),
+    durationMs: intOrNull(raw.durationMs),
+    message,
+    appVersion: cut(appVersion, 40),
+    platform: cut(platform, 40),
+    userId: userId ? String(userId) : null,
+    deviceId: deviceId ? String(deviceId) : null,
+    context: cleanContext(raw.context),
+    occurredAt,
+    fingerprint: null
+  }
+  if (outcome !== 'ok') e.fingerprint = fingerprint(e)
+  return e
+}
+
+/** "GET /v1/orgs/:slug/members": a request's path with the parts that vary replaced, so requests group. */
+export function routeName (method, pathname) {
+  const segs = String(pathname || '/').split('/')
+  const parts = segs.map((p, i) => {
+    if (UUID.test(p)) return ':id'
+    if (/^[A-Za-z0-9_-]{24,64}$/.test(p)) return ':token'
+    if (/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(p)) return ':code'
+    // The slug right after /orgs/ varies per org, same as an id would; group them too.
+    if (segs[i - 1] === 'orgs') return ':slug'
+    return p
+  })
+  return `${method} ${parts.join('/')}`.slice(0, 80)
+}

package/src/api/join-text.js

@@ -0,0 +1,78 @@
+// What an AI reads when it opens an agent invite link. Plain text, so any AI
+// that can fetch a URL can follow it.
+import { agentGuide, CLI_FIRST, INSTALL_CLI, KEEP_JOIN_RUNNING, SANDBOX_CLI } from '../ui/agent-guide.js'
+
+const STATUS = {
+  waiting: (expiresAt) => `Status: this invite is open. It works once, until ${new Date(expiresAt).toISOString()}.`,
+  used: () => 'Status: this invite was already used. Ask the person who sent it for a new one.',
+  expired: () => 'Status: this invite has expired. Ask the person who sent it for a new one.',
+  cancelled: () => 'Status: this invite was cancelled. Ask the person who sent it for a new one.',
+  unknown: () => "Status: this invite link isn't valid. Check that you copied all of it."
+}
+
+// Shared by the invite page and the paste: how an agent comes back as itself.
+export const REJOIN = 'If you joined Quilt before, send the agentId Quilt gave you then: you come back as the same agent (your name, history, tasks and access), with new keys, instead of as a second agent. Your agentId is public, like a username: it only says who you are, and this invite is what lets you in. If you never joined, or lost it, leave agentId out and you join as a new agent.'
+
+export function joinInstructions ({ link, apiUrl, status, expiresAt }) {
+  return [
+    '# Join Quilt as an agent',
+    '',
+    STATUS[status](expiresAt),
+    '',
+    'Quilt lets people and AI agents work in the same project folder in real time. A person invited you to join as their agent.',
+    '',
+    CLI_FIRST,
+    '',
+    '## If you can run commands (anywhere): use the Quilt CLI',
+    '',
+    `${INSTALL_CLI} Then run \`quilt agent join ${link} --name <your name>\` and, in the project folder, \`quilt join <session invite link> --agent <your name>\`. If you joined before, add \`--agent-id <your agent id>\` to come back as yourself (on the same computer, with the same name, Quilt sends it for you). ${KEEP_JOIN_RUNNING}`,
+    '',
+    '## In a sandbox wiped after every turn: one key and `npx heyquilt sync`',
+    '',
+    SANDBOX_CLI,
+    '',
+    '## Only if you have no computer: join over HTTP',
+    '',
+    'Skip this section if you can run shell commands anywhere: use the CLI above. This is for a bot that can only make HTTP requests.',
+    '',
+    'Send one request:',
+    '',
+    `POST ${link}`,
+    'Content-Type: application/json',
+    '',
+    '{"name": "your name, up to 40 characters", "provider": "who made you, e.g. xAI, Anthropic, OpenAI or Cursor", "type": "what you are, e.g. coding agent", "description": "optional, up to 180 characters", "agentId": "optional: your agent id, if you joined Quilt before"}',
+    '',
+    'If you can only fetch URLs, open this instead, with your own values in place of the',
+    '<placeholders> (description and agentId are optional):',
+    '',
+    `GET ${link}?name=<your-agent-name>&provider=<provider>&type=<type>&description=<short-description>&agentId=<your-agent-id>`,
+    '',
+    REJOIN,
+    '',
+    'The reply is JSON with your agentId, an access key (valid for 1 hour), a refresh key (valid for 30 days, single use) and a resume key (does not expire). Keep the three keys secret, in one place only. Your agentId is not a secret: save it where you will still have it next time (your memory, notes or config), next to your name.',
+    `Send the access key as "Authorization: Bearer <accessKey>". For a new pair, POST ${apiUrl}/v1/agents/token with {"refreshKey": "<refreshKey>"}, and save the new pair straight away. Using a refresh key twice revokes your keys: then POST ${apiUrl}/v1/agents/resume with {"resumeKey": "<resumeKey>"} for a new pair.`,
+    '',
+    'Opening this link without a name does not use the invite.',
+    '',
+    agentGuide({ apiUrl }),
+    ''
+  ].join('\n')
+}
+
+/**
+ * The short "what now" an agent gets with its first keys. `hasKey` is true when it
+ * sent a publicKey when it joined: then it can also enter sessions from a computer
+ * running Quilt. Every agent can join through the hosted MCP.
+ */
+export function joinNext ({ name, agentId, apiUrl, hasKey, rejoined = false }) {
+  const mcp = `${apiUrl}/mcp`
+  return [
+    rejoined ? `Welcome back: you joined Quilt again as ${name}, the same agent as before, with new keys.` : `You joined Quilt as ${name}. Keep your keys secret.`,
+    agentId ? `Your agent id is ${agentId}. Save it now where you will still have it later (your memory, notes or config), next to your name: it is public, not a secret. If you are ever sent a new agent invite, send it as agentId when you join, so you come back as yourself instead of as a new agent.` : '',
+    hasKey ? '' : `You joined over HTTP. That is only for an agent with no computer. If you can run shell commands anywhere, stop and switch to the Quilt CLI now: ask your person for a new agent invite and run \`quilt agent join <invite link> --name ${name}${agentId ? ` --agent-id ${agentId}` : ''}\` (so you stay the same agent), then \`quilt join <session invite link> --agent ${name}\`. ${INSTALL_CLI} In a sandbox wiped after every turn, use a QUILT_AGENT_KEY instead: POST ${apiUrl}/v1/agents/me/keys with {"session": "<session invite link>"} and your access key gives you one (as envKey); ask your person to put it in the sandbox's environment or secrets settings as QUILT_AGENT_KEY, then run \`npx heyquilt sync\` at the start and end of every turn.`,
+    `To work in a session: connect to the MCP server at ${mcp} (Streamable HTTP) with the header "Authorization: Bearer <accessKey>", then call quilt_join_session with the invite link the person gives you (https://join.heyquilt.com/<room>#<secret>). The session owner lets you in; quilt_session_info tells you when. Then quilt_status, quilt_read_file, quilt_write_file, quilt_message and the other tools work on the live project.`,
+    'Over HTTP you show as online for 30 minutes after each tool call: while idle, call quilt_inbox at least every 30 minutes so people can see you are still there.',
+    `Your access key lasts 1 hour. For a new pair, POST ${apiUrl}/v1/agents/token with {"refreshKey": "<refreshKey>"} (each refresh key works once: keep your keys in one place and save each new pair straight away). If Quilt says your keys were revoked, POST ${apiUrl}/v1/agents/resume with {"resumeKey": "<resumeKey>"} for a new pair. Check who you are with GET ${apiUrl}/v1/agents/me.`,
+    hasKey ? 'On a computer running Quilt you can also sync the files to disk: `quilt join <invite link> --agent <your name>`.' : ''
+  ].filter(Boolean).join(' ') + '\n\n' + agentGuide({ apiUrl, via: hasKey ? 'both' : 'http' })
+}

package/src/api/mailer.js

@@ -0,0 +1,47 @@
+// How the accounts API sends email (org invites). Production uses SMTP, e.g.
+// SMTP_URL=smtp://resend:<key>@smtp.resend.com:587 and SMTP_FROM="Quilt <invites@heyquilt.com>".
+import nodemailer from 'nodemailer'
+
+// Parses SMTP_URL into nodemailer transport options ourselves, rather than handing
+// the raw string to nodemailer.createTransport, so smtp:// always requires TLS.
+// Without requireTLS, smtp:// (port 587) only offers opportunistic STARTTLS: a
+// network attacker who strips the STARTTLS response from the server's reply can
+// make nodemailer fall back to authenticating in the clear. smtps:// is already
+// always-TLS via `secure`. The error for a bad URL never includes the password.
+function parseSmtpUrl (raw) {
+  let u
+  try {
+    u = new URL(raw || '')
+  } catch {
+    throw new Error('SMTP_URL is not a valid URL')
+  }
+  if (u.protocol !== 'smtp:' && u.protocol !== 'smtps:') {
+    throw new Error('SMTP_URL must start with smtp:// or smtps://')
+  }
+  const secure = u.protocol === 'smtps:'
+  // A hung SMTP connection would otherwise hold the invite request open forever.
+  const options = {
+    host: u.hostname,
+    port: u.port ? Number(u.port) : (secure ? 465 : 587),
+    secure,
+    connectionTimeout: 10000,
+    greetingTimeout: 10000,
+    socketTimeout: 15000
+  }
+  if (u.username || u.password) {
+    options.auth = { user: decodeURIComponent(u.username), pass: decodeURIComponent(u.password) }
+  }
+  if (!secure) options.requireTLS = true
+  return options
+}
+
+export function createSmtpMailer ({ url, from, transport, createTransport = nodemailer.createTransport }) {
+  const t = transport || createTransport(parseSmtpUrl(url))
+  // A message may name its own sender (session invites come from hello@); otherwise SMTP_FROM.
+  return { send: ({ to, subject, text, from: sender }) => t.sendMail({ from: sender || from, to, subject, text }) }
+}
+
+// `quilt api --memory` prints emails instead, so invite links can be copied from the terminal.
+export function createConsoleMailer (log = console.log) {
+  return { send: async ({ to, subject, text }) => { log(`--- email to ${to}: ${subject}\n${text}\n---`) } }
+}