@davait/aipictury 1.9.2

package/ext/browser.js

@@ -0,0 +1,263 @@
+'use strict'
+// A browser for the agent, as Claude Code's Chrome integration: it opens pages, reads them
+// (an accessibility snapshot whose elements carry refs — "[ref=e12]" — to act on), clicks,
+// types, takes screenshots for the vision model, reads the console. It drives the user's own
+// Chrome (or Edge, or Chromium) through Playwright, in a profile of its own
+// (~/.aipictury/browser) so sign-ins persist and the user's everyday profile is never touched;
+// the window is visible unless aipictury.browser.headless says otherwise.
+// No VS Code here: the agent decides what is asked, this only does it.
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { home } = require('./sessions')
+
+// What only looks, and what acts on a site (asked per site, not in Plan mode).
+const LOOKS = new Set(['snapshot', 'screenshot', 'console', 'tabs', 'wait'])
+const ACTS = new Set(['navigate', 'back', 'click', 'type', 'press', 'select', 'hover', 'evaluate', 'new_tab', 'close_tab', 'close'])
+const ACTIONS = [...LOOKS, ...ACTS]
+const SNAPSHOT_CAP = 24_000                       // characters of snapshot sent to the model
+const CONSOLE_KEEP = 200
+
+const state = { context: null, page: null, console: [], launching: null, channel: null, tmp: null }
+
+/** The site a call is about: the page it goes to, or the page it acts on. */
+function targetUrl(args) {
+  if (args.action === 'navigate' || args.action === 'new_tab') return String(args.url || '')
+  try { return state.page && !state.page.isClosed() ? state.page.url() : '' } catch { return '' }
+}
+
+/** Sites the agent may use without asking: the user's own machine. */
+function isLocal(url) {
+  try {
+    const { hostname, protocol } = new URL(url)
+    if (protocol === 'file:' || protocol === 'about:' || protocol === 'data:') return true
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname.endsWith('.localhost')
+  } catch { return false }
+}
+
+function hostOf(url) { try { return new URL(url).hostname.toLowerCase() } catch { return '' } }
+
+function profileDir() { return path.join(home(), 'browser') }
+
+/** Where Chrome, Edge or Chromium is installed here, as Playwright launches it: { channel } for
+ *  Chrome and Edge, { executablePath } for a Chromium. */
+function installs(platform = process.platform, env = process.env) {
+  const local = env.LOCALAPPDATA || ''
+  const pf = env.PROGRAMFILES || 'C:\\Program Files'
+  const pf86 = env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)'
+  const at = {
+    darwin: [['chrome', '/Applications/Google Chrome.app'], ['chrome', path.join(os.homedir(), 'Applications/Google Chrome.app')],
+      ['msedge', '/Applications/Microsoft Edge.app'], ['chromium', '/Applications/Chromium.app/Contents/MacOS/Chromium']],
+    linux: [['chrome', '/opt/google/chrome/chrome'], ['msedge', '/opt/microsoft/msedge/msedge'],
+      ['chromium', '/usr/bin/chromium'], ['chromium', '/usr/bin/chromium-browser'], ['chromium', '/snap/bin/chromium']],
+    win32: [['chrome', path.join(pf, 'Google/Chrome/Application/chrome.exe')], ['chrome', path.join(pf86, 'Google/Chrome/Application/chrome.exe')],
+      ['chrome', path.join(local, 'Google/Chrome/Application/chrome.exe')], ['msedge', path.join(pf86, 'Microsoft/Edge/Application/msedge.exe')],
+      ['msedge', path.join(pf, 'Microsoft/Edge/Application/msedge.exe')]],
+  }[platform] || []
+  return at.filter(([, p]) => p && fs.existsSync(p)).map(([kind, p]) => (kind === 'chromium' ? { kind, executablePath: p } : { kind, channel: kind }))
+}
+
+let found
+/** Is there a browser to drive (and Playwright to drive it)? Looked up once. */
+function available() {
+  if (found === undefined) {
+    let playwright = true
+    try { require.resolve('playwright-core') } catch { playwright = false }
+    found = playwright ? installs() : []
+  }
+  return found.length > 0
+}
+
+function track(page) {
+  const push = (line) => { state.console.push(line); if (state.console.length > CONSOLE_KEEP) state.console.shift() }
+  page.on('console', (m) => push(`${m.type()}: ${m.text()}`))
+  page.on('pageerror', (e) => push(`error: ${e.message}`))
+}
+
+/** The browser, opened on first use: the first channel found of Chrome, Edge, Chromium. */
+async function open({ headless = false, prefer = 'auto' } = {}) {
+  if (state.context) return state.page && !state.page.isClosed() ? state.page : newPage()
+  if (state.launching) return state.launching
+  state.launching = (async () => {
+    let chromium
+    try { ({ chromium } = require('playwright-core')) } catch { throw new Error('the browser needs Playwright, which is missing from this install of the extension') }
+    fs.mkdirSync(profileDir(), { recursive: true })
+    // Chrome on macOS drops a file of its own into the temp folder on each start; its temp
+    // files go to a folder of this browser instead, removed when it closes.
+    state.tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'aipictury-browser-'))
+    const errors = []
+    const all = installs()
+    const order = prefer === 'auto' ? all : [...all.filter((b) => b.kind === prefer), ...all.filter((b) => b.kind !== prefer)]
+    for (const b of order) {
+      try {
+        state.context = await chromium.launchPersistentContext(profileDir(), { channel: b.channel, executablePath: b.executablePath, headless,
+          viewport: { width: 1280, height: 860 }, env: { ...process.env, MAC_CHROMIUM_TMPDIR: state.tmp } })
+        state.channel = b.kind
+        break
+      } catch (error) { errors.push(`${b.kind}: ${String(error.message).split('\n')[0]}`) }
+    }
+    if (!state.context) {
+      fs.rmSync(state.tmp, { recursive: true, force: true })
+      throw new Error(`no browser could be opened — install Google Chrome or Microsoft Edge${errors.length ? ` (${errors.join('; ')})` : ''}`)
+    }
+    state.context.on('close', () => reset())
+    state.context.on('page', (p) => { track(p); state.page = p })        // a link that opens a tab: work there
+    for (const p of state.context.pages()) track(p)
+    state.page = state.context.pages()[0] || await state.context.newPage()
+    return state.page
+  })()
+  try { return await state.launching } finally { state.launching = null }
+}
+
+async function newPage() {
+  state.page = await state.context.newPage()
+  return state.page
+}
+
+function reset() {
+  if (state.tmp) fs.rmSync(state.tmp, { recursive: true, force: true })
+  Object.assign(state, { context: null, page: null, console: [], launching: null, channel: null, tmp: null })
+}
+
+async function close() {
+  const context = state.context
+  if (context) await context.close().catch(() => {})
+  reset()
+}
+
+/** The page as the model reads it: title, address, and its snapshot with refs. */
+async function snapshot(page) {
+  await page.waitForLoadState('domcontentloaded', { timeout: 15_000 }).catch(() => {})
+  let tree = await page.ariaSnapshot({ mode: 'ai', timeout: 15_000 })
+  if (tree.length > SNAPSHOT_CAP) tree = `${tree.slice(0, SNAPSHOT_CAP)}\n… (the page goes on — act on what is shown, or scroll with press "PageDown")`
+  const url = page.url()
+  return `Page: ${await page.title()} — ${url.length > 200 ? `${url.slice(0, 200)}…` : url}\n\n${tree}`
+}
+
+function locate(page, args) {
+  const ref = String(args.ref || '').replace(/^\[?ref=/, '').replace(/\]$/, '').trim()
+  if (!ref) throw new Error(`${args.action} needs the ref of an element from the snapshot (e.g. "e12")`)
+  return page.locator(`aria-ref=${ref}`)
+}
+
+/** After an action: the page settles a moment, and the model gets the page as it is now. */
+async function settled(page, said) {
+  await page.waitForLoadState('domcontentloaded', { timeout: 10_000 }).catch(() => {})
+  await page.waitForTimeout(300)
+  const current = state.page && !state.page.isClosed() ? state.page : page
+  return `${said}\n\n${await snapshot(current)}`
+}
+
+/**
+ * One browser action. Resolves to text for the model, or { text, images } for a screenshot.
+ * `options`: { headless, prefer: 'auto' | 'chrome' | 'msedge' | 'chromium' }.
+ */
+async function run(args, options = {}) {
+  const action = String(args.action || '')
+  if (!ACTIONS.includes(action)) throw new Error(`unknown action "${action}" — one of: ${ACTIONS.join(', ')}`)
+  if (action === 'close') { await close(); return 'The browser is closed.' }
+  const page = await open(options)
+  const timeout = 15_000
+  switch (action) {
+    case 'navigate': {
+      const url = String(args.url || '').trim()
+      if (!/^(https?|file|about|data):/i.test(url)) throw new Error('navigate needs a whole address, e.g. https://example.com')
+      const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 })
+      return `${response && !response.ok() ? `The server answered ${response.status()}.\n\n` : ''}${await snapshot(page)}`
+    }
+    case 'back': await page.goBack({ waitUntil: 'domcontentloaded', timeout }); return snapshot(page)
+    case 'snapshot': return snapshot(page)
+    case 'click': {
+      await locate(page, args).click({ timeout, button: args.button === 'right' ? 'right' : 'left', clickCount: args.double ? 2 : 1 })
+      return settled(page, `Clicked ${args.element || args.ref}.`)
+    }
+    case 'hover': await locate(page, args).hover({ timeout }); return settled(page, `Hovering over ${args.element || args.ref}.`)
+    case 'type': {
+      const target = locate(page, args)
+      await target.fill(String(args.text ?? ''), { timeout })
+      if (args.submit) await target.press('Enter', { timeout })
+      return settled(page, `Typed into ${args.element || args.ref}${args.submit ? ' and pressed Enter' : ''}.`)
+    }
+    case 'select': {
+      const values = Array.isArray(args.values) ? args.values.map(String) : [String(args.values ?? args.text ?? '')]
+      await locate(page, args).selectOption(values, { timeout })
+      return settled(page, `Selected ${values.join(', ')} in ${args.element || args.ref}.`)
+    }
+    case 'press': {
+      const key = String(args.key || '').trim()
+      if (!key) throw new Error('press needs a key, e.g. "Enter", "PageDown", "Control+A"')
+      await page.keyboard.press(key)
+      return settled(page, `Pressed ${key}.`)
+    }
+    case 'wait': {
+      if (args.text) {
+        await page.getByText(String(args.text)).first().waitFor({ timeout: Math.min(60, Number(args.seconds) || 20) * 1000 })
+        return `"${args.text}" is on the page.\n\n${await snapshot(page)}`
+      }
+      await page.waitForTimeout(Math.max(0.1, Math.min(30, Number(args.seconds) || 2)) * 1000)
+      return snapshot(page)
+    }
+    case 'screenshot': {
+      const png = await (args.ref ? locate(page, args).screenshot({ timeout }) : page.screenshot({ fullPage: !!args.full_page, timeout }))
+      return { text: `A screenshot of ${args.ref ? args.element || args.ref : `${await page.title()} — ${page.url()}`} (${png.length} bytes) — look at it.`,
+        images: [png.toString('base64')] }
+    }
+    case 'console': {
+      const lines = state.console.slice(-Math.max(1, Math.min(CONSOLE_KEEP, Number(args.limit) || 50)))
+      return lines.length ? `The console (oldest first):\n${lines.join('\n')}` : 'The console is empty.'
+    }
+    case 'evaluate': {
+      const script = String(args.script || '').trim()
+      if (!script) throw new Error('evaluate needs a script: a JavaScript expression, e.g. "document.title"')
+      const value = await page.evaluate(script)
+      const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+      return `Result: ${String(text ?? 'undefined').slice(0, 8000)}`
+    }
+    case 'tabs': {
+      const pages = state.context.pages()
+      if (args.index !== undefined) {
+        const chosen = pages[Number(args.index)]
+        if (!chosen) throw new Error(`there is no tab ${args.index} (there are ${pages.length})`)
+        state.page = chosen
+        await chosen.bringToFront()
+        return snapshot(chosen)
+      }
+      const titles = await Promise.all(pages.map(async (p, i) => `${i}${p === state.page ? ' (current)' : ''}: ${await p.title().catch(() => '')} — ${p.url()}`))
+      return `Tabs:\n${titles.join('\n')}`
+    }
+    case 'new_tab': {
+      const fresh = await newPage()
+      if (args.url) await fresh.goto(String(args.url), { waitUntil: 'domcontentloaded', timeout: 30_000 })
+      return snapshot(fresh)
+    }
+    case 'close_tab': {
+      await page.close()
+      const rest = state.context.pages()
+      state.page = rest.at(-1) || await newPage()
+      return `Tab closed.\n\n${await snapshot(state.page)}`
+    }
+    default: throw new Error(`unknown action "${action}"`)
+  }
+}
+
+/** One line for the panel's row. */
+function describe(args) {
+  const a = args.action
+  if (a === 'navigate' || a === 'new_tab') return `${a} ${args.url || ''}`.trim()
+  if (a === 'type') return `type into ${args.element || args.ref}`
+  if (a === 'press') return `press ${args.key || ''}`
+  if (['click', 'hover', 'select'].includes(a)) return `${a} ${args.element || args.ref || ''}`
+  return a || ''
+}
+
+/** A browser action that is always asked, whatever the mode: what goes into a password,
+ *  card or similar field — the agent never enters them unasked. Returns why, or null. */
+function sensitive(args) {
+  if (args.action !== 'type' && args.action !== 'select') return null
+  const about = `${args.element || ''} ${args.ref || ''}`
+  if (/pass(word|code|phrase)|contraseña|\bpin\b|one.?time|\botp\b|2fa|mfa|security code/i.test(about)) return 'it would type into a password or security-code field'
+  if (/card|cvv|cvc|iban|account number|routing|expir|ssn|social security|tax id/i.test(about)) return 'it would enter payment or identity details'
+  return null
+}
+
+module.exports = { run, close, open, targetUrl, isLocal, hostOf, describe, sensitive, available, installs, LOOKS, ACTS, ACTIONS, state, profileDir }

package/ext/cloud.js

@@ -0,0 +1,385 @@
+'use strict'
+// The cloud copy of what is yours, in Firestore under users/{uid} (docs/accounts-plan.md): the
+// projects and their conversations, project memory, your rules, your preferences, each day's
+// usage. Local-first: the editor and the CLI work from their own files and keep this copy in
+// step — a conversation is pushed when its content changed, conversations from another machine
+// are listed and downloaded when opened. Shared by the extension and the CLI; no VS Code here.
+const crypto = require('crypto')
+const zlib = require('zlib')
+const path = require('path')
+const { execFile } = require('child_process')
+const { Firestore } = require('./firestore')
+const { Storage } = require('./storage')
+
+const CHUNK = 700_000                    // characters of base64 a chunk (the rules allow 900,000)
+const MAX_CHUNKS = 64                    // ~45 MB of base64: a conversation larger than that stays local
+// Preferences that follow you. Nothing else is sent: never env, headers, tokens or MCP config.
+const PREFERENCES = ['effort', 'approval', 'showThinking', 'focusView', 'autoMemory', 'notifications',
+  'useCtrlEnterToSend', 'browser.headless', 'outputStyle', 'skillVisibility', 'enabledPlugins', 'permissions']
+
+const sha = (text) => crypto.createHash('sha256').update(text).digest('hex').slice(0, 40)
+
+/** A git remote as one string for the same repository everywhere: no scheme, user, credentials or .git. */
+function normalizeRemote(url) {
+  let u = String(url || '').trim()
+  if (!u) return ''
+  u = u.replace(/^[a-z+]+:\/\//i, '')               // https://, ssh://, git+ssh://
+    .replace(/^[^@/]*@/, '')                        // user@ or user:token@
+    .replace(/^([^/:]+):(?!\d+\/)/, '$1/')         // git@host:owner/repo → host/owner/repo
+    .replace(/:\d+\//, '/')                         // a port
+    .replace(/\.git\/?$/, '').replace(/\/+$/, '')
+  const [host, ...rest] = u.split('/')
+  return [host.toLowerCase(), ...rest].join('/')
+}
+
+function gitRemote(folder) {
+  return new Promise((resolve) => {
+    execFile('git', ['config', '--get', 'remote.origin.url'], { cwd: folder, timeout: 5000 }, (error, out) => resolve(error ? '' : out.trim()))
+  })
+}
+
+/** The project as the cloud knows it: { id, name, remote }. The same id on every machine for a git repository. */
+async function projectOf(folder) {
+  const remote = normalizeRemote(await gitRemote(folder))
+  const name = path.basename(folder || 'no-folder')
+  const id = remote ? `g-${sha(remote).slice(0, 24)}` : `l-${sha(path.resolve(folder || '/')).slice(0, 24)}`
+  return { id, name: remote ? remote.split('/').pop() : name, remote }
+}
+
+function pack(value) {
+  const json = JSON.stringify(value)
+  const data = zlib.gzipSync(json, { level: 9 }).toString('base64')
+  const chunks = []
+  for (let i = 0; i < data.length; i += CHUNK) chunks.push(data.slice(i, i + CHUNK))
+  return { hash: sha(json), chunks, bytes: json.length }
+}
+
+function unpack(chunks) {
+  return JSON.parse(zlib.gunzipSync(Buffer.from(chunks.join(''), 'base64')).toString('utf8'))
+}
+
+/** The GPU server compresses a clip to keep (media.compact): its progress through onStage, then
+ *  the figures — { original, size, saving, ssim, seconds, kept, why }. */
+async function compactOn(server, assetId, onStage) {
+  const r = await fetch(`${server}/api/assets/${assetId}/compact`, { method: 'POST', signal: AbortSignal.timeout(1_800_000) })
+  if (!r.ok) throw new Error(`the server could not compress it (${r.status})`)
+  let buffer = ''
+  let stats = null
+  for await (const chunk of r.body) {
+    buffer += Buffer.from(chunk).toString('utf8')
+    let at
+    while ((at = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, at).trim()
+      buffer = buffer.slice(at + 1)
+      if (!line) continue
+      const event = JSON.parse(line)
+      if (event.error) throw new Error(event.error)
+      if (event.phase === 'compress') onStage({ stage: 'compress', progress: event.progress })
+      if (event.done) stats = { original: event.original, size: event.size, saving: event.saving, ssim: event.ssim, seconds: event.seconds, kept: event.kept, why: event.why || '' }
+    }
+  }
+  if (!stats) throw new Error('the server stopped before it was compressed')
+  return stats
+}
+
+class Cloud {
+  /**
+   * `account`: account.js (who, and ID tokens). `device`: { id, name, app, platform, version }.
+   * `emulator`: "host:port" of the Firestore emulator (tests).
+   */
+  constructor({ account, projectId, device, emulator = null, bucket = null, storageEmulator = null, log = () => {}, fetchImpl }) {
+    this.account = account
+    this.device = device
+    this.log = log
+    this.db = new Firestore({ projectId, emulator, getToken: () => account.idToken(), fetchImpl })
+    this.storage = bucket ? new Storage({ bucket, emulator: storageEmulator, getToken: () => account.idToken(), fetchImpl }) : null
+    this.pushed = new Map()          // conversation path → hash last pushed (in this process)
+    this.timers = new Map()
+    // Signing out, or another account signing in, leaves nothing of the last session behind.
+    this.subscription = account.onChange?.(() => this.reset())
+  }
+
+  /** On sign-out (or another account signing in): nothing of the last session stays in memory —
+   *  scheduled pushes are cancelled, what was pushed is forgotten. */
+  reset() {
+    for (const t of this.timers.values()) clearTimeout(t)
+    this.timers.clear()
+    this.pushed.clear()
+  }
+
+  async uid() { return (await this.account.user())?.uid || null }
+  async base() {
+    const uid = await this.uid()
+    if (!uid) throw new Error('not signed in')
+    return `users/${uid}`
+  }
+
+  /** Says who this is and which device: called after signing in and now and then. */
+  async hello() {
+    const user = await this.account.user()
+    if (!user) return
+    const base = `users/${user.uid}`
+    const now = Date.now()
+    const existing = await this.db.get(base)
+    await this.db.set(base, { email: user.email || '', displayName: user.displayName || '', photoURL: user.photoURL || '',
+      created: existing?.created || now, lastSeen: now })
+    await this.db.set(`${base}/devices/${this.device.id}`, { name: this.device.name, app: this.device.app,
+      platform: this.device.platform, version: this.device.version, lastSeen: now })
+  }
+
+  // ---- conversations ----
+
+  async projectPath(folder) {
+    const p = await projectOf(folder)
+    return { ...p, path: `${await this.base()}/projects/${p.id}` }
+  }
+
+  /** Pushes one conversation (the entry the session store saves), when its content changed. */
+  async pushConversation(folder, entry) {
+    const project = await this.projectPath(folder)
+    const doc = `${project.path}/conversations/${entry.id}`
+    const content = { history: entry.history || [], transcript: entry.transcript || [], todos: entry.todos || [],
+      jobs: entry.jobs, btw: entry.btw }
+    const packed = pack(content)
+    if (packed.chunks.length > MAX_CHUNKS) { this.log(`cloud: ${entry.id} is too large to keep in the cloud (${packed.bytes} bytes)`); return 'too-large' }
+    // Two hashes: the content's (its chunks), and the whole one (with the title, group, archived),
+    // so renaming or archiving rewrites the summary only.
+    const summary = { title: String(entry.title || 'Conversation').slice(0, 300), renamed: !!entry.renamed,
+      aiTitle: entry.aiTitle ? String(entry.aiTitle).slice(0, 300) : '', group: entry.group || '', archived: !!entry.archived }
+    const whole = sha(packed.hash + JSON.stringify(summary))
+    if (this.pushed.get(doc) === whole) return 'unchanged'
+    const before = await this.db.get(doc)
+    if (before?.hash === whole) { this.pushed.set(doc, whole); return 'unchanged' }
+    const stale = []
+    if (before?.contentHash !== packed.hash) {
+      // The chunks first, the summary last: a reader that sees the summary finds every chunk.
+      for (const [i, data] of packed.chunks.entries()) await this.db.set(`${doc}/chunks/${i}`, { data, hash: packed.hash })
+      for (let i = packed.chunks.length; i < (before?.chunks || 0); i += 1) stale.push({ delete: `${doc}/chunks/${i}` })
+    }
+    await this.db.batch([...stale, { set: [doc, { ...summary,
+      created: entry.created || Date.now(), updated: entry.updated || Date.now(), model: entry.model || '',
+      turns: entry.usage?.turns || 0, usage: entry.usage || {},
+      origin: entry.origin || this.device.app, device: this.device.id, hash: whole, contentHash: packed.hash, chunks: packed.chunks.length, bytes: packed.bytes,
+    }] }])
+    await this.touchProject(project, folder)
+    this.pushed.set(doc, whole)
+    return before?.contentHash === packed.hash ? 'summary' : 'pushed'
+  }
+
+  async touchProject(project, folder) {
+    const current = await this.db.get(project.path)
+    const paths = [...new Set([...(current?.paths || []), path.resolve(folder)])].slice(-50)
+    await this.db.set(project.path, { name: project.name, remote: project.remote, paths, updated: Date.now(),
+      conversations: current?.conversations ?? 0 })
+  }
+
+  /** Pushes a few seconds after the last save, so a busy conversation is sent once, not at every step. */
+  async schedule(folder, entry, delayMs = 5000) {
+    // The push belongs to the account signed in now: if another one is by the time it runs, it is dropped.
+    const owner = await this.uid()
+    if (!owner) return
+    clearTimeout(this.timers.get(entry.id))
+    const timer = setTimeout(async () => {
+      this.timers.delete(entry.id)
+      if ((await this.uid()) !== owner) return
+      try { await this.pushConversation(folder, entry) } catch (error) { this.log(`cloud: ${entry.id} not pushed: ${error.message}`) }
+    }, delayMs)
+    timer.unref?.()
+    this.timers.set(entry.id, timer)
+  }
+
+  /** Waits for what is scheduled (on closing). */
+  async flush(pending) {
+    for (const t of this.timers.values()) clearTimeout(t)
+    this.timers.clear()
+    for (const [folder, entry] of pending || []) await this.pushConversation(folder, entry).catch(() => {})
+  }
+
+  /** A project's conversations, by its id (the web app's chats are the project "web"). */
+  async listProject(projectId) {
+    return (await this.db.list(`${await this.base()}/projects/${projectId}/conversations`)).map((d) => ({ id: d.id, ...d.data }))
+      .sort((a, b) => (b.updated || 0) - (a.updated || 0))
+  }
+
+  /** One conversation of a project, by the project's id: { meta, history, transcript, … }. */
+  async pullFrom(projectId, id) {
+    const doc = `${await this.base()}/projects/${projectId}/conversations/${id}`
+    const meta = await this.db.get(doc)
+    if (!meta) throw new Error('that conversation is not in your history any more')
+    const parts = []
+    for (let i = 0; i < meta.chunks; i += 1) {
+      const c = await this.db.get(`${doc}/chunks/${i}`)
+      if (!c || c.hash !== meta.contentHash) throw new Error('it is being saved right now — try again in a moment')
+      parts.push(c.data)
+    }
+    return { meta, ...unpack(parts) }
+  }
+
+  /** The cloud's summary of one of this project's conversations, or null. */
+  async summaryOf(folder, id) {
+    return this.db.get(`${(await this.projectPath(folder)).path}/conversations/${id}`)
+  }
+
+  /** This project's conversations in the cloud: [{ id, title, updated, origin, device, … }]. */
+  async listConversations(folder) {
+    const project = await this.projectPath(folder)
+    return (await this.db.list(`${project.path}/conversations`)).map((d) => ({ id: d.id, ...d.data }))
+      .sort((a, b) => (b.updated || 0) - (a.updated || 0))
+  }
+
+  /** The conversations of `folder` kept on this machine (`store`: sessions.js) that the account
+   *  lacks or has an older copy of, carried up; how many. `still()`: false stops (signed out). */
+  async bringUp(folder, store, { still = () => true } = {}) {
+    const remote = new Map((await this.listConversations(folder)).map((c) => [c.id, c]))
+    let up = 0
+    for (const meta of store.list().slice(0, 500)) {
+      if (!still()) break
+      const there = remote.get(meta.id)
+      if (there && (there.updated || 0) >= (meta.updated || 0)) continue
+      const entry = store.get(meta.id)
+      if (!entry) continue
+      try {
+        if (['pushed', 'summary'].includes(await this.pushConversation(folder, entry))) up += 1
+      } catch (err) { this.log(`cloud: ${meta.id} not carried up: ${err.message}`) }
+    }
+    return up
+  }
+
+  /** One conversation from the cloud, as the session store keeps it. */
+  async pullConversation(folder, id) {
+    const project = await this.projectPath(folder)
+    const doc = `${project.path}/conversations/${id}`
+    const meta = await this.db.get(doc)
+    if (!meta) throw new Error('that conversation is not in the cloud')
+    const parts = []
+    for (let i = 0; i < meta.chunks; i += 1) {
+      const c = await this.db.get(`${doc}/chunks/${i}`)
+      if (!c || c.hash !== meta.contentHash) throw new Error('the cloud copy is being written — try again in a moment')
+      parts.push(c.data)
+    }
+    const content = unpack(parts)
+    this.pushed.set(doc, meta.hash)
+    return { id, title: meta.title, renamed: meta.renamed, aiTitle: meta.aiTitle || undefined, created: meta.created, updated: meta.updated,
+      model: meta.model || null, usage: meta.usage, group: meta.group || undefined, archived: meta.archived || undefined, origin: meta.origin, ...content }
+  }
+
+  async deleteConversation(folder, id) {
+    const project = await this.projectPath(folder)
+    const doc = `${project.path}/conversations/${id}`
+    const meta = await this.db.get(doc)
+    const writes = []
+    for (let i = 0; i < (meta?.chunks || 0); i += 1) writes.push({ delete: `${doc}/chunks/${i}` })
+    writes.push({ delete: doc })
+    await this.db.batch(writes)
+    this.pushed.delete(doc)
+  }
+
+  // ---- memory, rules, preferences, usage ----
+
+  async getProjectMemory(folder) { return (await this.db.get(`${(await this.projectPath(folder)).path}/memory/current`)) || null }
+  async setProjectMemory(folder, text) {
+    await this.db.set(`${(await this.projectPath(folder)).path}/memory/current`, { text: String(text).slice(0, 200_000), updated: Date.now(), device: this.device.id })
+  }
+
+  /** Your rules: [{ id, text, created }]. */
+  async getRules() { return (await this.db.get(`${await this.base()}/memory/rules`))?.rules || [] }
+  async setRules(rules) { await this.db.set(`${await this.base()}/memory/rules`, { rules: rules.slice(0, 500), updated: Date.now() }) }
+
+  async getPreferences() { return (await this.db.get(`${await this.base()}/settings/preferences`)) || null }
+  /** This device's preferences, merged into the account's: what other apps keep there (the web
+   *  app's GPU server choice) stays. */
+  async setPreferences(values) {
+    const allowed = Object.fromEntries(Object.entries(values).filter(([k, v]) => PREFERENCES.includes(k) && v !== undefined))
+    const path = `${await this.base()}/settings/preferences`
+    const current = (await this.db.get(path))?.values || {}
+    await this.db.set(path, { values: { ...current, ...allowed }, updated: Date.now(), device: this.device.id })
+  }
+
+  /** Adds one turn to the day's totals. */
+  async addUsage(day, turn) {
+    const doc = `${await this.base()}/usage/${day}`
+    const now = (await this.db.get(doc)) || { turns: 0, prompt: 0, output: 0, genSeconds: 0, tools: {}, models: {} }
+    for (const t of turn.tools || []) now.tools[t] = (now.tools[t] || 0) + 1
+    for (const m of turn.models || []) now.models[m] = (now.models[m] || 0) + 1
+    await this.db.set(doc, { turns: now.turns + 1, prompt: now.prompt + (turn.context || 0), output: now.output + (turn.output || 0),
+      genSeconds: Math.round((now.genSeconds + (turn.genSeconds || 0)) * 10) / 10, tools: now.tools, models: now.models, updated: Date.now() })
+  }
+
+  /** Everything of yours in the cloud, deleted. The local files stay. */
+  /**
+   * A render the GPU server finished (its job), kept with the account as the web app keeps it:
+   * each file and a clip's poster in Storage (media/), its entry in renders/. Once per job;
+   * false when it was kept already or there is nothing to keep.
+   */
+  async keepRender(server, jobId, onStage = () => {}) {
+    if (!this.storage || !jobId) return false
+    const path = `${await this.base()}/renders/${jobId}`
+    if (await this.db.get(path)) return false
+    const r = await fetch(`${server}/api/jobs/${jobId}`, { signal: AbortSignal.timeout(20_000) })
+    if (!r.ok) throw new Error(`the job could not be read (${r.status})`)
+    const job = await r.json()
+    if (job.status !== 'done') return false
+    const media = `${await this.base()}/media`
+    const assets = []
+    for (const a of (job.assets_detail || []).slice(0, 8)) {
+      let stats = null
+      let stored
+      if (a.kind === 'video') {
+        // A clip: compressed on the GPU server first (MP4, H.264, never worse than as made).
+        stats = await compactOn(server, a.id, (s) => onStage(a.id, s))
+        const file = await fetch(`${server}/api/assets/${a.id}/compact`, { signal: AbortSignal.timeout(300_000) })
+        if (!file.ok) throw new Error(`the compressed clip could not be read (${file.status})`)
+        stored = `${media}/${a.id}.mp4`
+        onStage(a.id, { stage: 'upload', progress: 0 })
+        await this.storage.upload(stored, Buffer.from(await file.arrayBuffer()), 'video/mp4')
+        onStage(a.id, { stage: 'kept', stats })
+      } else {
+        const ext = (/\.[A-Za-z0-9]{1,5}$/.exec(a.filename || '') || ['.png'])[0]
+        const file = await fetch(`${server}/api/assets/${a.id}`, { signal: AbortSignal.timeout(300_000) })
+        if (!file.ok) throw new Error(`its file could not be read (${file.status})`)
+        stored = `${media}/${a.id}${ext}`
+        await this.storage.upload(stored, Buffer.from(await file.arrayBuffer()), file.headers.get('content-type') || 'image/png')
+      }
+      let poster = ''
+      if (a.kind === 'video') {
+        const p = await fetch(`${server}/api/assets/${a.id}/poster`, { signal: AbortSignal.timeout(30_000) }).catch(() => null)
+        if (p?.ok) { poster = `${media}/${a.id}-poster.jpg`; await this.storage.upload(poster, Buffer.from(await p.arrayBuffer()), p.headers.get('content-type') || 'image/jpeg') }
+      }
+      assets.push({ id: a.id, kind: a.kind === 'video' ? 'video' : 'image', path: stored, poster,
+        width: Number(a.width) || 0, height: Number(a.height) || 0, duration: Number(a.duration) || 0, ...(stats ? { stats } : {}) })
+    }
+    if (!assets.length) return false
+    await this.db.set(path, { kind: String(job.kind || '').slice(0, 40), prompt: String(job.params?.prompt || '').slice(0, 4000),
+      created: Math.round((Number(job.finished_at || job.created_at) || Date.now() / 1000) * 1000), assets, device: this.device.id })
+    return true
+  }
+
+  /** A conversation shared by remote control, listed with the account (aipictury.com offers to
+   *  control it): its link, title, machine; gone when sharing stops. */
+  async putRemote(id, { url, title, device, conversation = '' }) {
+    await this.db.set(`${await this.base()}/remote/${id}`, { url, title, device, conversation, started: Date.now(), updated: Date.now() })
+  }
+
+  async dropRemote(id) { await this.db.delete(`${await this.base()}/remote/${id}`) }
+
+  async deleteEverything() {
+    const base = await this.base()
+    const writes = []
+    for (const p of await this.db.list(`${base}/projects`)) {
+      for (const c of await this.db.list(`${base}/projects/${p.id}/conversations`)) {
+        for (let i = 0; i < (c.data.chunks || 0); i += 1) writes.push({ delete: `${base}/projects/${p.id}/conversations/${c.id}/chunks/${i}` })
+        writes.push({ delete: `${base}/projects/${p.id}/conversations/${c.id}` })
+      }
+      writes.push({ delete: `${base}/projects/${p.id}/memory/current` }, { delete: `${base}/projects/${p.id}` })
+    }
+    for (const col of ['usage', 'devices', 'renders', 'remote']) for (const d of await this.db.list(`${base}/${col}`)) writes.push({ delete: `${base}/${col}/${d.id}` })
+    writes.push({ delete: `${base}/memory/rules` }, { delete: `${base}/settings/preferences` }, { delete: base })
+    await this.db.batch(writes)
+    // The media kept with the account (pictures, clips, attachments) go too.
+    if (this.storage) for (const o of await this.storage.list(`${base}/media/`)) { await this.storage.delete(o.name); writes.push(o) }
+    this.pushed.clear()
+    return writes.length
+  }
+}
+
+module.exports = { Cloud, projectOf, normalizeRemote, pack, unpack, PREFERENCES, CHUNK, MAX_CHUNKS }