heartcode 0.0.0-stage → 0.1.1

package/src/probe.js

@@ -0,0 +1,343 @@
+// Capability probes: small, automatic tests that decide how HeartCode talks to a model.
+import path from 'node:path'
+import { deflateSync } from 'node:zlib'
+import { HOME, readJson, writeJson } from './config.js'
+import { est } from './client.js'
+import { contextWindow, contextSource, LOCAL_SERVERS, ASSUMED_REMOTE } from './context.js'
+import { loadPrices, limitsOf } from './usage.js'
+import { applyEdit, parseBlocks } from './edit.js'
+import { c } from './ui.js'
+import { log } from './log.js'
+import { prompt } from './prompts.js'
+
+// One cached profile per server + model. The URL path counts: proxies serve several providers
+// from one host (https://proxy.dev/groq, https://proxy.dev/openrouter).
+export const profilePath = (client) => {
+  const u = new URL(client.baseUrl)
+  const where = u.host + u.pathname.replace(/\/v1$/, '')
+  return path.join(HOME, 'models', `${where}_${client.model}`.replace(/[^\w.-]+/g, '_') + '.json')
+}
+// Bump when the probe learns something new, so older cached profiles are probed again once.
+const PROBE_VERSION = 2
+export const loadProfile = (client) => {
+  const p = readJson(profilePath(client), null)
+  return p?.version === PROBE_VERSION ? p : null
+}
+
+// --- tiny PNG encoder, for the vision probe ---
+const CRC = new Uint32Array(256).map((_, n) => {
+  let v = n
+  for (let k = 0; k < 8; k++) v = v & 1 ? 0xedb88320 ^ (v >>> 1) : v >>> 1
+  return v
+})
+const crc32 = (buf) => {
+  let v = 0xffffffff
+  for (const b of buf) v = CRC[(v ^ b) & 0xff] ^ (v >>> 8)
+  return (v ^ 0xffffffff) >>> 0
+}
+const pngChunk = (type, data) => {
+  const head = Buffer.alloc(4)
+  head.writeUInt32BE(data.length)
+  const body = Buffer.concat([Buffer.from(type), data])
+  const crc = Buffer.alloc(4)
+  crc.writeUInt32BE(crc32(body))
+  return Buffer.concat([head, body, crc])
+}
+export function solidPng(w, h, [r, g, b]) {
+  const ihdr = Buffer.alloc(13)
+  ihdr.writeUInt32BE(w, 0)
+  ihdr.writeUInt32BE(h, 4)
+  ihdr[8] = 8 // bit depth
+  ihdr[9] = 2 // RGB
+  const row = Buffer.alloc(1 + w * 3)
+  for (let x = 0; x < w; x++) row.set([r, g, b], 1 + x * 3)
+  const raw = Buffer.concat(Array(h).fill(row))
+  const sig = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])
+  return Buffer.concat([sig, pngChunk('IHDR', ihdr), pngChunk('IDAT', deflateSync(raw)), pngChunk('IEND', Buffer.alloc(0))])
+}
+
+const COLORS = { red: [220, 30, 30], green: [30, 170, 60], blue: [30, 60, 220], yellow: [245, 220, 30] }
+const firstInt = (t) => Number(/\d+/.exec(t)?.[0])
+
+// Rate limits, server errors and dropped connections are waited out (with the countdown, Esc
+// stops it), so a probe that starts finishes and is saved, and the model is never probed again.
+// A request the server rejects (400, 404 "no endpoint supports images", …) just means "no".
+const transient = (e) => !e.status || [408, 409, 429].includes(e.status) || e.status >= 500
+export async function probe(client, status, signal) {
+  const [retryIf, purpose] = [client.retryIf, client.purpose]
+  client.retryIf = (e, attempt) => transient(e) && attempt < 8 // about 4 minutes of waiting at most
+  client.purpose = 'test' // in the requests log
+  try {
+    return await runProbe(client, status, signal)
+  } finally {
+    Object.assign(client, { retryIf, purpose })
+  }
+}
+
+async function runProbe(client, report = () => {}, signal) {
+  const status = (label) => {
+    log('probe', label)
+    report(label)
+  }
+  const p = { version: PROBE_VERSION, model: client.model, baseUrl: client.baseUrl, probedAt: new Date().toISOString() }
+  let tokens = 0
+  let ms = 0
+  let calls = 0
+  let lastError = null
+  const chat = async (body, opts) => {
+    const t0 = Date.now()
+    const r = await client.chat({ temperature: 0, ...body }, { signal, ...opts }) // no max_tokens: the model decides how long
+    ms += Date.now() - t0
+    calls++
+    if (r.usage?.completion_tokens) p.usage = true
+    tokens += r.usage?.completion_tokens ?? est(r.content + r.reasoning)
+    if (r.thinking) p.thinking = true
+    return r
+  }
+  const say = (user, system) =>
+    chat({ messages: system ? [{ role: 'system', content: system }, { role: 'user', content: user }] : [{ role: 'user', content: user }] }).then((r) =>
+      r.content.trim(),
+    )
+  // A rejected request (400, 422, a 404 "no endpoint supports images", …) or an unparsable reply
+  // means "not supported". Dead connections, auth errors, rate limits, outages, and a model that
+  // was never reachable abort the probe, so a bad profile never gets cached.
+  const safe = async (fn) => {
+    try {
+      return Boolean(await fn())
+    } catch (e) {
+      if (e.name === 'AbortError' || /^cannot reach/.test(e.message)) throw e
+      if ([401, 429].includes(e.status) || e.status >= 500 || ([403, 404].includes(e.status) && !calls))
+        throw new Error(`probe stopped, nothing saved: ${e.message}`)
+      lastError = e
+      return false
+    }
+  }
+  const trials = async (label, fns) => {
+    status(label)
+    let pass = 0
+    for (const fn of fns) if (await safe(fn)) pass++
+    return { pass, total: fns.length }
+  }
+
+  status('streaming')
+  let streamed = 0
+  p.stream = await safe(async () => {
+    const r = await chat({ messages: [{ role: 'user', content: prompt('probe/hello') }], stream: true }, { onToken: () => streamed++ })
+    return streamed > 0 || r.thinking
+  })
+
+  status('context size')
+  // what the server is and says; else models.dev's published size (context.js decides between them)
+  const found = await client.contextSize()
+  p.server = found.server
+  p.context = found.size || (LOCAL_SERVERS.includes(found.server) ? 4096 : ASSUMED_REMOTE)
+  p.contextGuessed = !found.size
+  await loadPrices()
+  const known = limitsOf(client.provider, client.baseUrl, client.model)
+  if (known) p.known = known
+
+  p.system = await trials(
+    'system prompt',
+    ['What is 2 + 2?', 'Name a color.'].map((q) => async () => /banana/i.test(await say(q, prompt('probe/system')))),
+  )
+
+  p.format = await trials(
+    'exact format',
+    [7, 42].map((n) => async () => (await say(prompt('probe/exact-number', { n }))).replace(/[.\s`*"']/g, '') === String(n)),
+  )
+
+  const menus = [
+    ['a fruit', ['a hammer', 'an apple', 'a car'], 2],
+    ['an animal', ['a river', 'a chair', 'a dog'], 3],
+    ['a color', ['blue', 'a table', 'a spoon'], 1],
+  ]
+  p.menu = await trials(
+    'menu picking',
+    menus.map(([what, opts, ans]) => async () => {
+      const list = opts.map((o, i) => `${i + 1}. ${o}`).join('\n')
+      return firstInt(await say(prompt('probe/menu', { what, list }))) === ans
+    }),
+  )
+
+  status('stop sequences')
+  p.stop = await safe(async () => {
+    const r = await chat({ messages: [{ role: 'user', content: prompt('probe/count') }], stop: ['5'] })
+    return /4/.test(r.content) && !/6/.test(r.content)
+  })
+
+  const tool = {
+    type: 'function',
+    function: {
+      name: 'get_secret_code',
+      description: prompt('probe/tool-description'),
+      parameters: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+    },
+  }
+  const toolMsg = (name) => ({ role: 'user', content: prompt('probe/tool-question', { name }) })
+  const toolCall = (r, name) => {
+    const call = r.toolCalls.find((t) => t.function.name === 'get_secret_code')
+    try {
+      return call && String(JSON.parse(call.function.arguments).name).toLowerCase().includes(name) ? call : null
+    } catch {
+      return null
+    }
+  }
+  p.tools = await trials(
+    'tool calls',
+    ['alpha', 'falcon', 'ember'].map((n) => async () => toolCall(await chat({ messages: [toolMsg(n)], tools: [tool] }), n)),
+  )
+  if (p.tools.pass) {
+    status('tool results')
+    p.toolResult = await safe(async () => {
+      const r = await chat({ messages: [toolMsg('alpha')], tools: [tool] })
+      const call = toolCall(r, 'alpha')
+      if (!call) return false
+      const r2 = await chat({
+        messages: [
+          toolMsg('alpha'),
+          { role: 'assistant', content: r.content || '', tool_calls: [call] },
+          { role: 'tool', tool_call_id: call.id, content: prompt('probe/tool-result') },
+        ],
+        tools: [tool],
+      })
+      return r2.content.includes('4417')
+    })
+    status('streamed tool calls')
+    p.toolsStream = await safe(async () => toolCall(await chat({ messages: [toolMsg('falcon')], tools: [tool], stream: true }), 'falcon'))
+
+  }
+
+  status('constrained output')
+  const words = ['zebra-purple', 'mango-teal']
+  p.constrained = await safe(async () => {
+    const schema = { type: 'object', properties: { word: { type: 'string', enum: words } }, required: ['word'], additionalProperties: false }
+    const r = await chat({
+      messages: [{ role: 'user', content: prompt('probe/capital') }],
+      response_format: { type: 'json_schema', json_schema: { name: 'probe', strict: true, schema } },
+    })
+    return words.includes(JSON.parse(r.content).word)
+  })
+
+  const names = Object.keys(COLORS).sort(() => Math.random() - 0.5).slice(0, 2)
+  p.vision = await trials(
+    'vision',
+    names.map((name) => async () => {
+      const url = 'data:image/png;base64,' + solidPng(256, 256, COLORS[name]).toString('base64')
+      const r = await chat({
+        messages: [{ role: 'user', content: [{ type: 'text', text: prompt('probe/image-color') }, { type: 'image_url', image_url: { url } }] }],
+      })
+      const t = r.content.toLowerCase()
+      return t.includes(name) && Object.keys(COLORS).every((k) => k === name || !t.includes(k))
+    }),
+  )
+
+  const cases = [
+    {
+      code: 'function add(a, b) {\n  return a + b\n}\n\nfunction sub(a, b) {\n  return a - b\n}\n',
+      ask: 'Change the add function so it returns a * b instead of a + b.',
+      ok: (t) => t.includes('return a * b') && t.includes('return a - b'),
+    },
+    {
+      code: 'const greeting = "hello"\nconsole.log(greeting)\n',
+      ask: 'Change the greeting from "hello" to "good morning".',
+      ok: (t) => t.includes('good morning') && t.includes('console.log(greeting)'),
+    },
+  ]
+  p.edit = await trials(
+    'edit skill',
+    cases.map((cs) => async () => {
+      const reply = await say(prompt('probe/edit', { code: cs.code, ask: cs.ask }))
+      let text = cs.code
+      const blocks = parseBlocks(reply)
+      for (const b of blocks) {
+        const r = applyEdit(text, b.search, b.replace)
+        if (r.error) return false
+        text = r.text
+      }
+      return blocks.length > 0 && cs.ok(text)
+    }),
+  )
+
+  p.speed = ms ? Math.round(tokens / (ms / 1000)) : 0
+  p.latency = calls ? Math.round(ms / calls) : 0
+  // Every request failed: that's a broken model or endpoint, not a weak model.
+  if (!calls) throw new Error(`probe stopped, nothing saved: no request succeeded${lastError ? ` (last error: ${lastError.message})` : ''}`)
+  log('probe', 'result', p)
+  writeJson(profilePath(client), p)
+  return p
+}
+
+const all = (s) => Boolean(s && s.total && s.pass === s.total)
+const most = (s) => Boolean(s && s.total && s.pass * 3 >= s.total * 2)
+
+// A model's profile without testing it: what models.dev says (info: limitsOf), or, for a model it
+// doesn't know, plain assumptions (source 'assumed': tool calls, streaming, a 128k window) until you
+// say on the settings page what it can do (set: { context, tools, thinking, images, stream },
+// source 'you'). Profiles from a test (/test_model, heart probe) have no source.
+export function profileFrom(client, info) {
+  return { version: PROBE_VERSION, model: client.model, baseUrl: client.baseUrl, source: info ? 'models.dev' : 'assumed', at: new Date().toISOString(), usage: true, context: ASSUMED_REMOTE, contextGuessed: true, ...(info && { known: info }) }
+}
+
+// Turns a profile into decisions. Your settings for the model (p.set) come first; then, for a model
+// that wasn't tested, what models.dev says; for a tested one, what the test found. Config/flags
+// can override the window (--context).
+export function strategy(p, cfg = {}) {
+  const set = p.set ?? {}
+  const said = p.source ? (p.known ?? {}) : null // not tested: models.dev's word (or nothing known)
+  const tools = set.tools ?? (said ? said.tools !== false : most(p.tools) && p.toolResult)
+  const thinking = set.thinking ?? (said ? Boolean(said.thinking) : Boolean(p.thinking))
+  const stream = set.stream ?? (said ? true : Boolean(p.stream))
+  const win = contextWindow(p)
+  return {
+    actions: tools ? 'tools' : 'guided',
+    edits: said || all(p.edit) ? 'search_replace' : 'rewrite',
+    enforce: !said && Boolean(p.constrained),
+    stream,
+    toolsStream: stream && (said ? true : Boolean(p.toolsStream)),
+    stop: said ? !thinking : Boolean(p.stop), // stop sequences cut into a thinking model's thinking
+    mergeSystem: said ? false : !most(p.system),
+    vision: set.images ?? (said ? Boolean(said.images) : all(p.vision)),
+    thinking,
+    context: cfg.context || set.context || win.size, // context.js: measured, said, models.dev, learned, or assumed
+    contextSure: Boolean(cfg.context || set.context) || win.sure,
+    reply: p.known?.output, // the longest reply it gives (models.dev), room kept for it
+    ratio: p.tokenRatio ?? 1, // the server's tokens per estimated token
+  }
+}
+
+export function describe(p, s) {
+  const yn = (v) => (v ? c.green('yes') : c.red('no'))
+  const score = (x) => {
+    if (!x) return c.dim('–')
+    const t = `${x.pass}/${x.total}`
+    return x.pass === x.total ? c.green(t) : x.pass ? c.yellow(t) : c.red(t)
+  }
+  const context = ['context', `${s.context}${c.dim(`  (${p.set?.context ? 'set by you on /settings' : contextSource(p)}; change it on /settings)`)}`]
+  // not tested: where it's from, and what it can do
+  if (p.source) {
+    const from = { 'models.dev': 'models.dev', you: 'you, on /settings', assumed: "nothing: it isn't in models.dev. Set what it can do on /settings" }[p.source]
+    const mine = (k) => (p.set?.[k] !== undefined ? c.dim('  (set by you)') : '')
+    return [['from', from], context, ['tool calls', yn(s.actions === 'tools') + mine('tools')], ['thinking', yn(s.thinking) + mine('thinking')], ['images', yn(s.vision) + mine('images')], ['streaming', yn(s.stream) + mine('stream')]]
+      .map(([k, v]) => `  ${c.dim(k.padEnd(15))} ${v}`)
+      .join('\n')
+  }
+  const rows = [
+    ['streaming', yn(p.stream) + (p.thinking ? c.dim('  (thinking model)') : '')],
+    context,
+    ['system prompt', score(p.system)],
+    ['exact format', score(p.format)],
+    ['menu picking', score(p.menu)],
+    ['stop sequences', yn(p.stop) + (!p.stop && p.thinking ? c.dim('  (they cut into the thinking; not used)') : '')],
+    ['tool calls', score(p.tools) + (p.tools?.pass ? c.dim(`  uses results: ${p.toolResult ? 'yes' : 'no'} · streamed: ${p.toolsStream ? 'yes' : 'no'}`) : '')],
+    ['constrained', yn(p.constrained)],
+    ['vision', score(p.vision)],
+    ['edit skill', score(p.edit)],
+    ['speed', `${p.speed} tok/s` + (p.latency ? c.dim(`  · ${(p.latency / 1000).toFixed(1)}s per reply`) : '')],
+  ]
+  const lines = rows.map(([k, v]) => `  ${c.dim(k.padEnd(15))} ${v}`)
+  lines.push(
+    `  ${c.bold('→')} actions: ${c.cyan(s.actions)} · edits: ${c.cyan(s.edits)}` +
+      `${s.enforce ? ' · enforced answers' : ''}${s.vision ? ' · images' : ''}${s.mergeSystem ? ' · system→user' : ''}`,
+  )
+  return lines.join('\n')
+}

package/src/prompts.js

@@ -0,0 +1,104 @@
+// Every text HeartCode sends to a model is a section of a markdown file in prompts/ (agent.md,
+// guided.md, compact.md, probe.md). prompt('guided/next-action') is the "## next-action" section of
+// guided.md. The user's own sections override the built-in ones, by name:
+//   ~/.heart/prompts/<file>.md          for every project
+//   <project>/.heartcode/prompts/<file>.md   for one project
+// In a section:
+//   {{name}}                              filled in from `vars`; a missing one is an error
+//   {{#if name}} … {{else}} … {{/if}}     optional parts (else is optional)
+//   <!-- … -->                             a note right under the heading; never sent
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { HOME } from './config.js'
+
+const BUILTIN = fileURLToPath(new URL('../prompts/', import.meta.url))
+let project = null
+const cache = new Map()
+
+// The project whose .heartcode/prompts and HEARTCODE.md apply.
+export function usePromptsFrom(root) {
+  project = root
+  cache.clear()
+}
+
+// After the user's sections changed (the settings page): read again, from the next message.
+export const reloadPrompts = () => cache.clear()
+export const BUILTIN_PROMPTS = BUILTIN
+
+// "## name" sections of a markdown file (text before the first heading is the file's own notes).
+export function sections(text) {
+  const out = new Map()
+  let name = null
+  let lines = []
+  const flush = () => name && out.set(name, lines.join('\n').replace(/^\s*<!--[\s\S]*?-->\s*/, '').replace(/^\s+|\s+$/g, ''))
+  for (const line of text.split('\n')) {
+    const h = /^## (\S+)\s*$/.exec(line)
+    if (h) {
+      flush()
+      ;[name, lines] = [h[1], []]
+    } else if (name) lines.push(line)
+  }
+  flush()
+  return out
+}
+
+function load(file) {
+  if (!cache.has(file)) {
+    const merged = new Map()
+    for (const dir of [BUILTIN, path.join(HOME, 'prompts'), project && path.join(project, '.heartcode', 'prompts')]) {
+      if (!dir) continue
+      try {
+        for (const [k, v] of sections(fs.readFileSync(path.join(dir, `${file}.md`), 'utf8'))) merged.set(k, v)
+      } catch {}
+    }
+    cache.set(file, merged)
+  }
+  return cache.get(file)
+}
+
+export function prompt(id, vars = {}) {
+  const i = id.indexOf('/')
+  const text = load(id.slice(0, i)).get(id.slice(i + 1))
+  if (text === undefined) throw new Error(`no prompt "${id}" (a "## ${id.slice(i + 1)}" section in prompts/${id.slice(0, i)}.md)`)
+  return text
+    .replace(/\{\{#if (\w+)\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if\}\}/g, (m, k, yes, no = '') => (vars[k] ? yes : no))
+    .replace(/\{\{\s*(\w+)\s*\}\}/g, (m, k) => {
+      if (!(k in vars)) throw new Error(`prompt "${id}" needs {{${k}}}`)
+      return String(vars[k])
+    })
+}
+
+// The user's standing instructions: ~/.heart/HEARTCODE.md, then the project's own file. The project's
+// is HEARTCODE.md, or else the first other tool's file found (so a project set up for another CLI
+// works as is). Only one, so the same rules never cost twice. '' when there are none.
+export const INSTRUCTION_FILES = ['HEARTCODE.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.github/copilot-instructions.md', '.cursorrules']
+
+export function userInstructions(root = project) {
+  const read = (f) => {
+    try {
+      return fs.readFileSync(f, 'utf8').trim()
+    } catch {
+      return ''
+    }
+  }
+  let local = ''
+  for (const f of root ? INSTRUCTION_FILES : []) if ((local = read(path.join(root, f)))) break
+  if (!local && root) local = cursorRules(root)
+  return [read(path.join(HOME, 'HEARTCODE.md')), local].filter(Boolean).join('\n\n')
+}
+
+// Cursor's .cursor/rules/*.mdc: the ones marked "alwaysApply: true", without their front matter.
+function cursorRules(root) {
+  const dir = path.join(root, '.cursor', 'rules')
+  let files = []
+  try {
+    files = fs.readdirSync(dir).filter((f) => /\.mdc?$/.test(f)).sort()
+  } catch {}
+  return files
+    .map((f) => fs.readFileSync(path.join(dir, f), 'utf8'))
+    .map((t) => /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(t))
+    .filter((m) => m && /^alwaysApply:\s*true/m.test(m[1]))
+    .map((m) => m[2].trim())
+    .join('\n\n')
+}

package/src/reset.js

@@ -0,0 +1,49 @@
+// /reset: HeartCode's own files in ~/.heart back to how they were before you changed anything.
+// Three levels, each including the one before. A project's own .heartcode/ is never touched.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { HOME, CONFIG_FILE, readJson, writeJson } from './config.js'
+
+export const RESETS = [
+  {
+    level: 'settings',
+    label: 'Settings',
+    desc: 'permissions, theme, effort, the toggles, the model list, voice; your keys, colors, formatters, prompts, MCP servers and hooks. Your providers, keys and model stay.',
+    files: ['keybindings.json', 'theme.json', 'format.json', 'prompts', 'mcp.json', 'hooks.json'],
+  },
+  {
+    level: 'providers',
+    label: 'Settings and providers',
+    desc: 'the above, and your providers with their API keys, MCP sign-ins, what HeartCode learned about each model, prices',
+    files: ['config.json', 'mcp-auth.json', 'models', 'prices.json'],
+  },
+  {
+    level: 'everything',
+    label: 'Everything',
+    desc: `the above, and your sessions, global memory, skills, instructions (HEARTCODE.md), history, logs: all of ${HOME}`,
+    files: null, // the whole folder
+  },
+]
+
+// What a level removes, for the question (the files that are there).
+export function resetPaths(level) {
+  const upto = RESETS.slice(0, RESETS.findIndex((r) => r.level === level) + 1)
+  if (upto.at(-1).files === null) return fs.existsSync(HOME) ? fs.readdirSync(HOME).map((f) => path.join(HOME, f)) : []
+  return upto.flatMap((r) => r.files).map((f) => path.join(HOME, f)).filter((f) => fs.existsSync(f))
+}
+
+export function reset(level) {
+  if (!RESETS.some((r) => r.level === level)) throw new Error(`no reset "${level}"`)
+  const files = resetPaths(level)
+  if (level === 'settings') {
+    // config.json: only who answers stays (providers, keys, the model)
+    const cfg = readJson(CONFIG_FILE, null)
+    if (cfg) writeJson(CONFIG_FILE, Object.fromEntries(Object.entries(cfg).filter(([k]) => ['providers', 'provider', 'model'].includes(k))))
+  }
+  for (const f of files) fs.rmSync(f, { recursive: true, force: true })
+  return files
+}
+
+// A code to type before resetting: 4 letters and digits that can't be mistaken for each other.
+export const resetCode = () => Array.from(crypto.randomBytes(4), (b) => 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'[b % 31]).join('')

package/src/sessions.js

@@ -0,0 +1,135 @@
+// Saved conversations: one file per chat in ~/.heart/sessions, written after every message, so a
+// chat can be resumed later and rewound to any earlier message (conversation, files, or both).
+import fs from 'node:fs'
+import path from 'node:path'
+import { HOME, readJson, writeJson } from './config.js'
+
+const DIR = path.join(HOME, 'sessions')
+
+// A chat: what the model has seen (messages for tool mode, history for guided mode), what the
+// screen showed (log), and per message ("turn") where each of those stood and the files as they
+// were before HeartCode first changed them in that turn (null = the file didn't exist).
+export function newChat(root) {
+  const now = new Date()
+  const id = `${now.toISOString().slice(0, 19).replace(/[-:T]/g, '')}-${Math.random().toString(36).slice(2, 6)}`
+  return { id, root, created: now.toISOString(), updated: now.toISOString(), title: '', messages: null, history: [], turns: [], log: [] }
+}
+
+export function saveChat(chat) {
+  const file = path.join(DIR, `${chat.id}.json`)
+  const first = chat.turns[0] ?? chat.branches?.[0]?.state.turns[0] // gone back to the start: its branches remain
+  if (!first) return fs.rmSync(file, { force: true }) // nothing (left) worth keeping
+  chat.updated = new Date().toISOString()
+  chat.title = chat.name || first.task.split('\n')[0].slice(0, 80) // its name (/rename), else the first message, even after a rewind
+  writeJson(file, chat)
+}
+
+// /fork: a copy of the chat to go on with (the original stays as it is, in /resume).
+export function forkChat(chat) {
+  const copy = { ...structuredClone(chat), id: newChat(chat.root).id, created: new Date().toISOString() }
+  copy.name = `${chat.name || chat.title || 'chat'} (fork)`
+  return copy
+}
+
+// The conversation as the model saw it, for /export: [{ role, text, tools: [{ name, args, result }] }].
+function entries(chat) {
+  const text = (c) => (Array.isArray(c) ? c.map((p) => (p.type === 'text' ? p.text : '[image]')).join('\n') : String(c ?? ''))
+  if (!chat.messages?.length) return chat.history.flatMap((h) => [{ role: 'user', text: h.task }, { role: 'assistant', text: h.answer }])
+  const out = []
+  const calls = new Map()
+  for (const m of chat.messages.slice(1)) {
+    if (m.role === 'tool') {
+      const t = calls.get(m.tool_call_id)
+      if (t) t.result = text(m.content)
+      continue
+    }
+    const e = { role: m.role, text: text(m.content).trim(), tools: (m.tool_calls ?? []).map((t) => ({ name: t.function.name, args: t.function.arguments })) }
+    m.tool_calls?.forEach((t, i) => calls.set(t.id, e.tools[i]))
+    if (e.text || e.tools.length) out.push(e)
+  }
+  return out
+}
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[ch])
+const fence = (s) => { const f = '`'.repeat(Math.max(3, ...[...String(s).matchAll(/`+/g)].map((m) => m[0].length + 1))); return `${f}\n${s}\n${f}` }
+
+// format: 'md', 'html' or 'json' (the whole session file)
+export function exportChat(chat, format, model = '') {
+  if (format === 'json') return JSON.stringify(chat, null, 2) + '\n'
+  const title = chat.name || chat.title || chat.turns[0]?.task.split('\n')[0] || 'HeartCode chat'
+  const when = `${new Date(chat.created).toLocaleString()}${model ? ` · ${model}` : ''} · ${chat.root}`
+  const list = entries(chat)
+  if (format === 'md') {
+    const body = list.map((e) => {
+      const tools = e.tools.map((t) => `<details><summary>${t.name} ${esc(t.args.slice(0, 120))}</summary>\n\n${fence(t.result ?? '')}\n</details>`).join('\n')
+      return [`## ${e.role === 'user' ? 'You' : 'HeartCode'}`, e.text, tools].filter(Boolean).join('\n\n')
+    })
+    return `# ${title}\n\n_${when}_\n\n${body.join('\n\n')}\n`
+  }
+  const body = list.map((e) => {
+    const tools = e.tools.map((t) => `<details><summary><b>${esc(t.name)}</b> <code>${esc(t.args.slice(0, 160))}</code></summary><pre>${esc(t.result ?? '')}</pre></details>`).join('')
+    return `<section class="${e.role}"><h2>${e.role === 'user' ? 'You' : 'HeartCode'}</h2>${e.text ? `<div class="text">${esc(e.text)}</div>` : ''}${tools}</section>`
+  })
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(title)}</title>
+<style>
+:root { --bg: #fff; --fg: #1d1f23; --muted: #6b7080; --user: #f3f0ff; --line: #e3e5ea; --code: #f6f7f9 }
+@media (prefers-color-scheme: dark) { :root { --bg: #16181d; --fg: #e6e8ec; --muted: #9aa0ad; --user: #241f36; --line: #2c3038; --code: #1e2127 } }
+body { background: var(--bg); color: var(--fg); font: 15px/1.55 system-ui, sans-serif; max-width: 860px; margin: 0 auto; padding: 24px 16px }
+header p { color: var(--muted); margin-top: -8px }
+section { border-top: 1px solid var(--line); padding: 12px 0 }
+section.user { background: var(--user); border-radius: 8px; padding: 12px 16px; border: 0; margin: 12px 0 }
+h2 { font-size: 13px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); margin: 0 0 6px }
+.text { white-space: pre-wrap; overflow-wrap: anywhere }
+details { margin: 6px 0; font-size: 13px }
+summary { cursor: pointer; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
+pre { background: var(--code); padding: 10px; border-radius: 6px; overflow-x: auto; max-height: 400px; white-space: pre-wrap }
+</style></head><body>
+<header><h1>${esc(title)}</h1><p>${esc(when)}</p></header>
+${body.join('\n')}
+</body></html>
+`
+}
+
+// One chat by its id (any folder), or null.
+export function loadChat(id) {
+  return /^[\w.-]+$/.test(id) ? readJson(path.join(DIR, `${id}.json`), null) : null
+}
+
+// This folder's chats, newest first.
+export function listChats(root) {
+  let files = []
+  try {
+    files = fs.readdirSync(DIR).filter((f) => f.endsWith('.json'))
+  } catch {}
+  return files
+    .map((f) => readJson(path.join(DIR, f), null))
+    .filter((c) => c && c.root === root && (c.turns?.length || c.branches?.length))
+    .sort((a, b) => b.updated.localeCompare(a.updated))
+}
+
+// Puts files back as they were before turn `from` (later turns first, so the oldest copy wins).
+// Returns the files touched.
+export function restoreFiles(chat, from) {
+  const touched = new Set()
+  for (const turn of chat.turns.slice(from).reverse()) {
+    for (const [rel, before] of Object.entries(turn.files)) {
+      const abs = path.resolve(chat.root, rel)
+      if (before === null) fs.rmSync(abs, { force: true })
+      else {
+        fs.mkdirSync(path.dirname(abs), { recursive: true })
+        fs.writeFileSync(abs, before)
+      }
+      touched.add(rel)
+    }
+  }
+  return [...touched]
+}
+
+export const ago = (iso) => {
+  const s = (Date.now() - Date.parse(iso)) / 1000
+  if (s < 60) return 'just now'
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`
+  return `${Math.floor(s / 86400)}d ago`
+}