heartcode 0.0.0-stage → 0.1.0

package/src/usage.js

@@ -0,0 +1,134 @@
+// Tokens used and what they cost, per chat (chat.usage). Prices per million tokens come from
+// models.dev's list of models (https://models.dev/api.json), kept a day in ~/.heart/prices.json,
+// and so does what each model is: its context window, longest reply, and whether it calls tools,
+// thinks and reads images (limitsOf). HeartCode takes a model's abilities from there.
+// A model it doesn't list (a local one, a provider it doesn't know) counts tokens only.
+import path from 'node:path'
+import { HOME, readJson, writeJson } from './config.js'
+import { log } from './log.js'
+
+const FILE = path.join(HOME, 'prices.json')
+const DAY = 86_400_000
+const VERSION = 3 // 2: with each model's limits; 3: and its abilities
+let table = null // { v, at, providers: { id: { api, models: { id: { input, output, cache_read, cache_write, limit: { context, output }, can: { tools, thinking, images } } } } } }
+
+// Loads the list (from the file if it's from today, else from models.dev). Never throws.
+// force: fetched again however fresh the saved one is (the settings page's retry); its failure throws.
+export async function loadPrices({ url = 'https://models.dev/api.json', timeout = 15_000, force = false } = {}) {
+  table ??= readJson(FILE, null)
+  const asked = arguments[0]?.url || force // a list from somewhere else, or asked for again: always fetched
+  if (!asked && ((table?.v === VERSION && Date.now() - table.at < DAY) || process.env.HEART_NO_PRICES)) return table // tests: no network
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeout) })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const data = await res.json()
+    const providers = {}
+    for (const [id, p] of Object.entries(data)) {
+      const models = {}
+      for (const [m, info] of Object.entries(p.models ?? {})) {
+        const price = info.cost && (({ input, output, cache_read, cache_write }) => ({ input, output, cache_read, cache_write }))(info.cost)
+        const limit = info.limit?.context > 0 ? { context: info.limit.context, output: info.limit.output > 0 ? info.limit.output : undefined } : undefined
+        const can = { tools: info.tool_call !== false, thinking: Boolean(info.reasoning), images: Array.isArray(info.modalities?.input) ? info.modalities.input.includes('image') : Boolean(info.attachment) }
+        if (price || limit) models[m] = { ...price, limit, can }
+      }
+      providers[id] = { api: p.api, models }
+    }
+    table = { v: VERSION, at: Date.now(), providers }
+    writeJson(FILE, table)
+  } catch (e) {
+    log('prices', `could not load the price list: ${e.message}`)
+    if (force) throw new Error(`couldn't reach models.dev: ${e.message}`)
+  }
+  return table
+}
+
+const norm = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9]/g, '')
+const hostOf = (url) => {
+  try {
+    return new URL(url).host
+  } catch {
+    return ''
+  }
+}
+
+// The price of a model at a provider (HeartCode's name for it and its URL), or null. The provider
+// models.dev knows by that name or URL first, else any provider that lists the model.
+export function priceOf(provider, baseUrl, model) {
+  if (!table || !model) return null
+  const all = Object.entries(table.providers)
+  const ids = [model, model.split('/').pop()]
+  const find = (list) => {
+    for (const [, p] of list) for (const id of ids) if (p.models[id]?.input !== undefined) return (({ limit, can, ...price }) => price)(p.models[id])
+    return null
+  }
+  const own = all.filter(ownBy(provider, baseUrl))
+  return find(own) ?? find(all)
+}
+// models.dev's providers that are this one: by its name in HeartCode, or its URL.
+const ownBy = (provider, baseUrl) => {
+  const host = hostOf(baseUrl)
+  return ([id, p]) => norm(id) === norm(provider) || (p.api && hostOf(p.api) === host) || (host.includes(id) && id.length > 3)
+}
+
+// models.dev's models with a size, by their names made plain (norm), the whole name and its last
+// part: built once per list, so a lookup doesn't go through all of them (thousands) again.
+const indexes = new WeakMap()
+function indexOf(t) {
+  if (indexes.has(t)) return indexes.get(t)
+  const index = new Map()
+  let n = 0 // its place in the list: ties go to the first, as they did before the index
+  for (const entry of Object.entries(t.providers)) {
+    for (const [m, info] of Object.entries(entry[1].models)) {
+      if (!info.limit) continue
+      const hit = { entry, info, n: n++ }
+      for (const k of new Set([norm(m), norm(m.split('/').pop())])) index.has(k) ? index.get(k).push(hit) : index.set(k, [hit])
+    }
+  }
+  indexes.set(t, index)
+  return index
+}
+
+// What models.dev says of a model: { context, output (tokens), tools, thinking, images }, or null. Found by its name
+// however it's written (google/gemini-2.5-flash, models/gemini-2.5-flash, gpt-oss:120b ≈
+// gpt-oss-120b): at this provider first; else, among all that list it, the size most say (a
+// proxy or a provider models.dev doesn't know serves the model at its usual size).
+export function limitsOf(provider, baseUrl, model) {
+  if (!table || !model) return null
+  const last = (m) => m.split('/').pop()
+  const want = new Set([model, model.replace(/^models\//, ''), last(model), last(model).replace(/:(free|beta|extended|nitro|floor|online|cloud)$/, '').replace(/-cloud$/, '')].map(norm))
+  const own = ownBy(provider, baseUrl)
+  const found = { own: [], all: [] }
+  const hits = [...new Set([...want].flatMap((w) => indexOf(table).get(w) ?? []))].sort((a, b) => a.n - b.n)
+  for (const { entry, info } of hits) {
+    const it = { ...info.limit, ...(info.can ?? { tools: true, thinking: false, images: false }) }
+    found.all.push(it)
+    if (own(entry)) found.own.push(it)
+  }
+  const list = found.own.length ? found.own : found.all
+  if (!list.length) return null
+  const count = (x) => list.filter((y) => y.context === x.context).length
+  const best = list.reduce((a, b) => (count(b) > count(a) || (count(b) === count(a) && b.context > a.context) ? b : a))
+  return { context: best.context, output: best.output, tools: best.tools, thinking: best.thinking, images: best.images }
+}
+
+// Adds one request's usage (OpenAI's names) to the total; returns what it cost (0 if unknown).
+export function addUsage(total, u, price) {
+  const input = u?.prompt_tokens ?? 0
+  const output = u?.completion_tokens ?? 0
+  const cached = u?.prompt_tokens_details?.cached_tokens ?? 0
+  const written = u?.cache_write_tokens ?? 0
+  let cost = 0
+  if (typeof u?.cost === 'number') cost = u.cost // OpenRouter says what it charged
+  else if (price) cost = ((input - cached - written) * (price.input ?? 0) + cached * (price.cache_read ?? price.input ?? 0) + written * (price.cache_write ?? price.input ?? 0) + output * (price.output ?? 0)) / 1e6
+  Object.assign(total, {
+    requests: (total.requests ?? 0) + 1,
+    input: (total.input ?? 0) + input,
+    output: (total.output ?? 0) + output,
+    cached: (total.cached ?? 0) + cached,
+    cost: (total.cost ?? 0) + cost,
+    priced: total.priced || Boolean(price) || typeof u?.cost === 'number',
+  })
+  return cost
+}
+
+export const money = (n) => (n >= 1 ? `$${n.toFixed(2)}` : n >= 0.01 ? `$${n.toFixed(3)}` : n > 0 ? `$${n.toFixed(4)}` : '$0')

package/src/voice.js

@@ -0,0 +1,97 @@
+// Voice input: Ctrl+R (or /voice) records from the microphone; Enter or Ctrl+R again stops, Esc
+// cancels; the words go into the input box, to read over and send.
+// Recording: ffmpeg (macOS: the default microphone; Linux: PulseAudio, else ALSA). Speech to text:
+//   - on this machine with whisper.cpp's whisper-cli and a model already on disk (~/.whisper-models,
+//     ~/.heart/whisper, or "voice": { "model": "/path/ggml-….bin" } in config.json); nothing is
+//     downloaded;
+//   - or a provider's OpenAI-compatible /audio/transcriptions: "voice": { "provider": "groq",
+//     "model": "whisper-large-v3" }.
+// "voice": { "language": "auto" } for languages other than English (with a multilingual model).
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { HOME } from './config.js'
+import { runCommand } from './tools.js'
+import { log } from './log.js'
+
+const onPath = (cmd) => (process.env.PATH ?? '').split(path.delimiter).find((d) => d && fs.existsSync(path.join(d, cmd)))
+
+// A whisper.cpp model already on disk: the configured one, else the best found (small > base > tiny).
+export function localModel(cfg = {}) {
+  if (cfg.model && fs.existsSync(cfg.model)) return cfg.model
+  const found = [path.join(os.homedir(), '.whisper-models'), path.join(HOME, 'whisper')].flatMap((d) => {
+    try {
+      return fs.readdirSync(d).filter((f) => /^ggml-.*\.bin$/.test(f)).map((f) => path.join(d, f))
+    } catch {
+      return []
+    }
+  })
+  const rank = (f) => ['large', 'medium', 'small', 'base', 'tiny'].findIndex((s) => path.basename(f).includes(s))
+  return found.sort((a, b) => (rank(a) === -1 ? 9 : rank(a)) - (rank(b) === -1 ? 9 : rank(b)))[0] ?? null
+}
+
+// Why voice can't work here, or null when it can.
+export function voiceProblem(cfg = {}, providers = {}) {
+  if (!onPath('ffmpeg')) return 'voice input needs ffmpeg to record (brew install ffmpeg)'
+  if (cfg.provider) return providers[cfg.provider] ? null : `voice.provider "${cfg.provider}" isn't one of your providers`
+  if (!onPath('whisper-cli')) return 'voice input needs whisper-cli (brew install whisper-cpp) and a model, or "voice": { "provider": …, "model": … } in ~/.heart/config.json'
+  return localModel(cfg) ? null : 'voice input needs a whisper model: put a ggml-*.bin in ~/.whisper-models, or set "voice": { "model": "/path/to/ggml-….bin" }'
+}
+
+// Starts recording to a 16 kHz mono WAV. Returns { stop() → the file, cancel() }.
+export function record() {
+  const file = path.join(os.tmpdir(), `heartcode-voice-${process.pid}-${Date.now()}.wav`)
+  const input = process.platform === 'darwin' ? ['-f', 'avfoundation', '-i', ':default'] : ['-f', 'pulse', '-i', 'default']
+  const start = (inp) => spawn('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', ...inp, '-ac', '1', '-ar', '16000', file], { stdio: ['pipe', 'ignore', 'pipe'] })
+  let child = start(input)
+  let err = ''
+  child.stderr.on('data', (d) => (err += d))
+  child.stdin.on('error', () => {})
+  const ended = () =>
+    new Promise((resolve) => {
+      if (child.exitCode !== null) return resolve()
+      child.once('exit', resolve)
+    })
+  return {
+    async stop() {
+      child.stdin.end('q') // ffmpeg finishes the file on "q"
+      const t = setTimeout(() => child.kill('SIGINT'), 3000)
+      await ended()
+      clearTimeout(t)
+      if (!fs.existsSync(file) || fs.statSync(file).size < 2000) throw new Error(`nothing was recorded${err.trim() ? `: ${err.trim().split('\n').pop()}` : ' (does the terminal have microphone access? System Settings › Privacy & Security › Microphone)'}`)
+      return file
+    },
+    cancel() {
+      child.kill('SIGKILL')
+      fs.rmSync(file, { force: true })
+    },
+  }
+}
+
+// The words in the recording (and the file is deleted).
+export async function transcribe(file, cfg = {}, providers = {}, signal) {
+  try {
+    if (cfg.provider) {
+      const p = providers[cfg.provider]
+      const form = new FormData()
+      form.append('file', new Blob([fs.readFileSync(file)], { type: 'audio/wav' }), 'speech.wav')
+      form.append('model', cfg.model ?? 'whisper-1')
+      if (cfg.language && cfg.language !== 'auto') form.append('language', cfg.language)
+      const res = await fetch(`${p.baseUrl.replace(/\/+$/, '')}/audio/transcriptions`, { method: 'POST', body: form, headers: p.apiKey ? { authorization: `Bearer ${p.apiKey}` } : {}, signal })
+      if (!res.ok) throw new Error(`${cfg.provider} said ${res.status}: ${(await res.text()).slice(0, 200)}`)
+      return clean((await res.json()).text)
+    }
+    const model = localModel(cfg)
+    const { code, output, stderr } = await runCommand(os.tmpdir(), `whisper-cli -m '${model}' -f '${file}' -nt -np -l ${cfg.language ?? 'en'} -t ${Math.max(2, Math.min(8, os.cpus().length))}`, { signal, timeout: 120_000, split: true }) // its log goes to stderr
+    log('voice', `whisper-cli → exit ${code}`, output.slice(0, 2000))
+    if (code !== 0) throw new Error(`whisper-cli failed: ${(stderr || output).trim().split('\n').pop()}`)
+    return clean(output)
+  } finally {
+    fs.rmSync(file, { force: true })
+  }
+}
+
+// One line of text: whisper's line breaks joined, and what it writes for sounds that aren't words
+// dropped: [BLANK_AUDIO], [Music], (wind blowing), (speaking foreign language)…
+export const clean = (t) => String(t ?? '').replace(/\[[^\]]*\]|\([^)]*\)/g, '').replace(/\s+/g, ' ').trim()

package/src/web.js

@@ -0,0 +1,123 @@
+// web_fetch and web_search: a page as text, and search results, with no API key.
+// Search scrapes DuckDuckGo's HTML page (asked twice when it answers with its bot check). Bing,
+// Startpage and Mojeek were tried too: blocked, or junk results for scripts.
+// ponytail: scraping, no API; add a keyed backend (Brave, Tavily) if DuckDuckGo blocks for good.
+
+const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124 Safari/537.36'
+const HEADERS = { 'user-agent': UA, accept: 'text/html,application/xhtml+xml,application/json;q=0.9,*/*;q=0.8', 'accept-language': 'en-US,en;q=0.9' }
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', rsquo: '’', lsquo: '‘', rdquo: '”', ldquo: '“', copy: '©' }
+export const decode = (s) =>
+  s.replace(/&(#x[\da-f]+|#\d+|\w+);/gi, (m, e) => {
+    if (e[0] === '#') {
+      const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))
+      return n > 0 && n < 0x110000 ? String.fromCodePoint(n) : m
+    }
+    return ENTITIES[e.toLowerCase()] ?? m
+  })
+
+// HTML → readable text: scripts, styles and page furniture dropped; headings, list items, links
+// and code blocks kept in a markdown-ish form.
+export function htmlToText(html, base) {
+  let h = String(html)
+  const title = decode(/<title[^>]*>([\s\S]*?)<\/title>/i.exec(h)?.[1]?.trim() ?? '')
+  const main = /<(main|article)\b[\s\S]*?<\/\1>/i.exec(h)?.[0] // the page's content, when it marks it
+  if (main && main.length > 500) h = main
+  h = h
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(script|style|noscript|svg|head|title|nav|footer|iframe|template|form)\b[\s\S]*?<\/\1>/gi, '')
+    .replace(/<pre\b[^>]*>([\s\S]*?)<\/pre>/gi, (m, code) => `\n\`\`\`\n${code.replace(/<[^>]+>/g, '')}\n\`\`\`\n`)
+    .replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi, (m, n, t) => `\n\n${'#'.repeat(Number(n))} ${t.replace(/<[^>]+>/g, '').trim()}\n\n`)
+    .replace(/<a\b[^>]*href="([^"#][^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, (m, href, t) => {
+      const text = t.replace(/<[^>]+>/g, '').trim()
+      if (!text) return ''
+      let url = decode(href)
+      try {
+        url = new URL(url, base).href
+      } catch {}
+      return /^https?:/.test(url) && text !== url ? `[${text}](${url})` : text
+    })
+    .replace(/<li\b[^>]*>/gi, '\n- ')
+    .replace(/<(br|hr)\b[^>]*>/gi, '\n')
+    .replace(/<\/(p|div|section|tr|table|ul|ol|blockquote|dd|dt)>/gi, '\n')
+    .replace(/<\/(td|th)>/gi, ' | ')
+    .replace(/<code\b[^>]*>([\s\S]*?)<\/code>/gi, '`$1`')
+    .replace(/<[^>]+>/g, '')
+  const text = decode(h)
+    .split('\n')
+    .map((l) => l.replace(/[ \t ]+/g, ' ').trimEnd())
+    .join('\n')
+    .replace(/\n\s*\n(?=- )/g, '\n') // list items one per line
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+  return title && !text.startsWith(`# ${title}`) ? `# ${title}\n\n${text}` : text
+}
+
+const MAX = 10_000 // a part and its note fit in a tool result (agent.js keeps 12,000 characters of one)
+
+// A page's text, from `start` (characters), for the model.
+export async function webFetch(url, { start = 0, signal } = {}) {
+  let u
+  try {
+    u = new URL(/^\w+:\/\//.test(url) ? url : `https://${url}`)
+  } catch {
+    return `error: "${url}" is not a URL`
+  }
+  if (!/^https?:$/.test(u.protocol)) return 'error: only http and https URLs can be fetched'
+  const res = await fetch(u, { headers: HEADERS, redirect: 'follow', signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) })
+  const type = res.headers.get('content-type') ?? ''
+  if (!/text|json|xml|javascript|markdown/.test(type) && type) return `error: ${u.href} is ${type.split(';')[0]}, not text (${res.status})`
+  const body = await res.text()
+  const text = /html/.test(type) || /^\s*<(!doctype|html)/i.test(body) ? htmlToText(body, res.url) : body
+  const from = Math.max(0, Number(start) || 0)
+  const part = text.slice(from, from + MAX)
+  const more = from + MAX < text.length ? `\n\n… (${text.length} characters in all; call web_fetch with start: ${from + MAX} for more)` : ''
+  return `${res.ok ? '' : `error: HTTP ${res.status}\n`}${res.url !== u.href ? `(redirected to ${res.url})\n` : ''}${part || '(empty page)'}${more}`
+}
+
+const strip = (s) => decode(String(s).replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim()
+
+async function duckduckgo(query, signal) {
+  let html = ''
+  for (let i = 0; i < 2; i++) {
+    const res = await fetch(process.env.HEART_SEARCH_URL || 'https://html.duckduckgo.com/html/', { // HEART_SEARCH_URL: a stand-in (tests)
+      method: 'POST',
+      headers: { ...HEADERS, 'content-type': 'application/x-www-form-urlencoded', referer: 'https://html.duckduckgo.com/' },
+      body: new URLSearchParams({ q: query, b: '' }),
+      signal,
+    })
+    html = await res.text()
+    if (res.status !== 202) break // 202: its bot check
+    if (i === 0) await new Promise((r) => setTimeout(r, 1500))
+    else throw new Error('DuckDuckGo is asking for a captcha')
+  }
+  const out = []
+  for (const m of html.matchAll(/<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>([\s\S]*?)(?=<a[^>]*class="result__a"|$)/g)) {
+    let url = decode(m[1])
+    const wrapped = /[?&]uddg=([^&]+)/.exec(url) // a DuckDuckGo redirect link
+    if (wrapped) url = decodeURIComponent(wrapped[1])
+    if (/duckduckgo\.com\/y\.js/.test(url)) continue // an ad
+    out.push({ title: strip(m[2]), url, snippet: strip(/class="result__snippet"[^>]*>([\s\S]*?)<\/a>/.exec(m[3])?.[1] ?? '') })
+  }
+  return out
+}
+
+export const ENGINES = { duckduckgo }
+
+// Results as text: title, URL and snippet, numbered.
+export async function webSearch(query, { signal, limit = 8, engines = ENGINES } = {}) {
+  const q = String(query ?? '').trim()
+  if (!q) return 'error: no query given'
+  const failed = []
+  for (const [name, engine] of Object.entries(engines)) {
+    try {
+      const hits = (await engine(q, signal ? AbortSignal.any([signal, AbortSignal.timeout(20_000)]) : AbortSignal.timeout(20_000))).filter((h) => h.url && h.title)
+      if (hits.length) return hits.slice(0, limit).map((h, i) => `${i + 1}. ${h.title}\n   ${h.url}${h.snippet ? `\n   ${h.snippet}` : ''}`).join('\n\n')
+      failed.push(`${name}: no results`)
+    } catch (e) {
+      if (signal?.aborted) throw e
+      failed.push(`${name}: ${e.message}`)
+    }
+  }
+  return `no results for "${q}" (${failed.join('; ')}). Try other words, or web_fetch a site you know.`
+}

package/src/worktree.js

@@ -0,0 +1,56 @@
+// heartcode -w / --worktree=name: work in a git worktree of its own, on its own branch, so the
+// task's changes stay apart from yours until you merge them. It goes in
+// <repo>/.heartcode/worktrees/<name> (kept out of git status), on the branch heartcode/<name>,
+// from the current commit. The same name again continues in the same worktree.
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+
+export function createWorktree(root, name) {
+  let top
+  try {
+    top = git(root, ['rev-parse', '--show-toplevel'])
+  } catch {
+    throw new Error(`--worktree needs a git repository; ${root} isn't in one`)
+  }
+  const stamp = new Date().toISOString().slice(0, 16).replace(/[-:T]/g, '')
+  name = String(name || `task-${stamp}`).replace(/[^\w.-]+/g, '-')
+  const dir = path.join(top, '.heartcode', 'worktrees', name)
+  const branch = `heartcode/${name}`
+  const base = git(top, ['rev-parse', 'HEAD'])
+  if (!fs.existsSync(dir)) {
+    const exists = (() => {
+      try {
+        git(top, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])
+        return true
+      } catch {
+        return false
+      }
+    })()
+    git(top, ['worktree', 'add', ...(exists ? [dir, branch] : ['-b', branch, dir, 'HEAD'])])
+  }
+  // keep the worktrees out of the main checkout's git status and file list
+  const exclude = path.join(path.resolve(top, git(top, ['rev-parse', '--git-common-dir'])), 'info', 'exclude')
+  const text = fs.existsSync(exclude) ? fs.readFileSync(exclude, 'utf8') : ''
+  if (!text.split('\n').includes('.heartcode/worktrees/')) {
+    fs.mkdirSync(path.dirname(exclude), { recursive: true })
+    fs.appendFileSync(exclude, `${text && !text.endsWith('\n') ? '\n' : ''}.heartcode/worktrees/\n`)
+  }
+  return { name, dir, branch, top, base, cwd: path.join(dir, path.relative(top, root)) }
+}
+
+// What the worktree holds now: uncommitted changes and commits on its branch since it was made.
+export function worktreeState(wt) {
+  const changes = git(wt.dir, ['status', '--porcelain']).split('\n').filter(Boolean).length
+  const commits = Number(git(wt.dir, ['rev-list', '--count', `${wt.base}..HEAD`]))
+  return { changes, commits, empty: !changes && !commits }
+}
+
+export function removeWorktree(wt) {
+  git(wt.top, ['worktree', 'remove', '--force', wt.dir])
+  try {
+    git(wt.top, ['branch', '-D', wt.branch])
+  } catch {}
+}