heartcode 0.1.15 → 0.1.24

package/src/agent.js

@@ -4,12 +4,14 @@ import { log } from './log.js'
 import { prompt, userInstructions } from './prompts.js'
 import { newChat } from './sessions.js'
 import path from 'node:path'
-import { est, Client, writtenBy } from './client.js'
+import { pathToFileURL } from 'node:url'
+import { est, Client, writtenBy, tokensOf, COMPACT_SHARE } from './client.js'
 import { runGuided } from './guided.js'
-import { TOOL_DEFS, PLAN_HIDDEN, extraTools, runTool, listFiles, namedFiles, readFileTool, clip, allowed, loadMcpTools, saveOutput, OUTPUTS, imageUrl, MAX_IMAGE, failed } from './tools.js'
+import { TOOL_DEFS, PLAN_HIDDEN, folderView, readOnlyCommand, extraTools, runTool, listFiles, namedFiles, readFileTool, clip, allowed, loadMcpTools, saveOutput, OUTPUTS, imageUrl, MAX_IMAGE, failed } from './tools.js'
+import { serversNote } from './lsp.js'
 import { loadHooks, runHooks } from './hooks.js'
 import { takeConfigErrors } from './config.js'
-import { c } from './ui.js'
+import { c, duration } from './ui.js'
 
 // Images for a helper (the agent tool's "images"), as data: URLs: image URLs (fetched), data: URLs,
 // or files: in the project, saved screenshots (OUTPUTS), or a path the user gave in a message.
@@ -97,7 +99,8 @@ export class Session {
   // midTask: compacting in the middle of a task, so the model is told to carry on with `task`
   // (the user's request, kept word for word).
   // The conversation before is kept per compaction ("epoch"), so /rewind can still go back.
-  async compact({ signal, focus = '', midTask = false, task = '' } = {}) {
+  // why: what the spinner says the compacting is for ("context 85% full (650k/768k)").
+  async compact({ signal, focus = '', midTask = false, task = '', why = '' } = {}) {
     const { chat, client, strat, ui } = this
     const native = Boolean(chat.messages?.length)
     const head = native ? chat.messages.slice(0, chat.messages[0].role === 'system' ? 1 : 2) : [] // the system prompt stays
@@ -107,7 +110,7 @@ export class Session {
     const room = Math.floor((strat.context * 0.6 * 3.5) / (strat.ratio ?? 1)) // characters of conversation the summary request can carry
     const cut = () => (conversation.length > room ? `[… the earliest part is cut]\n${conversation.slice(-room)}` : conversation)
     const before = native ? size(body) : est(conversation)
-    ui.spinner(midTask ? 'context almost full: compacting the conversation' : 'compacting the conversation')
+    ui.spinner(why ? `${why}: compacting the conversation` : 'compacting the conversation')
     // A model shown its own work tends to carry on with it (calling tools, or writing tool calls
     // as text) instead of summarizing: so it's told what it is, and a reply that isn't a summary
     // is asked for again once; then the compaction fails (the conversation is trimmed instead).
@@ -133,7 +136,9 @@ export class Session {
     }
     chat.history.splice(0, chat.history.length, { task: '(the conversation before this point, summarized)', answer: summary })
     const after = native ? size(chat.messages.slice(head.length)) : est(summary)
-    log('compact', `${midTask ? 'auto' : 'manual'}: ~${before} → ~${after} tokens`, summary)
+    log('compact', `${midTask ? 'auto' : 'manual'}${why ? ` (${why})` : ''}: ~${before} → ~${after} tokens`, summary)
+    client.lastTokens = 0 // the server's count was for the conversation before: none yet for this one
+    this.counted = null
     ui.stopSpin()
     ui.print(`${c.faint('✻')} ${c.muted(`Compacted the conversation: ~${kTokens(before)} → ~${kTokens(after)} tokens`)}`)
     return summary
@@ -202,7 +207,8 @@ export class Session {
     const self = { provider: this.client.provider, model: this.client.model, images: this.strat.vision, tools: this.strat.actions === 'tools', self: true }
     const all = [self, ...(this.team?.() ?? [])]
     const want = String(args.model ?? '').trim()
-    const first = !want ? self : (all.find((t) => name(t) === want) ?? all.find((t) => t.model === want || want.endsWith(` ${t.model}`)))
+    // only one model available (a pinned model, or you have just one): helpers use it, whatever was asked
+    const first = !want || all.length === 1 ? self : (all.find((t) => name(t) === want) ?? all.find((t) => t.model === want || want.endsWith(` ${t.model}`)))
     if (!first) return `error: no model "${want}". Yours: ${all.map(name).join(', ')}`
     // the one asked for first (if it can do the job), then the others that can: those that call
     // tools first, then the ones that failed least this session, in your list's order
@@ -402,10 +408,23 @@ export class Session {
 // A program's own instructions (--append-system-prompt: Nibedita, a script) come last, and HeartCode's
 // own say less then (caller): no role of its own, no "stay in the folder", no way to finish of its
 // own, no director; they're told to follow the program's where they differ.
+// One line of context about where HeartCode runs, so the model knows the OS, shell and tools to expect.
+const OS_NAMES = { darwin: 'macOS', linux: 'Linux', win32: 'Windows' }
+const envLine = () => {
+  const shell = (process.env.SHELL || process.env.ComSpec || '').split(/[/\\]/).pop()
+  return `${OS_NAMES[process.platform] ?? process.platform} (${process.platform} ${os.release()}, ${process.arch})${shell ? `, shell ${shell}` : ''}`
+}
+
+// The project root's entries, every one (names only), for the system prompt.
+const rootList = (root) => {
+  const v = folderView(root)
+  return v.error ? `(can't read it: ${v.error})` : v.entries.length ? v.entries.join(' · ') + (v.more ? ` · … ${v.more} more` : '') : '(empty)'
+}
+
 const SYSTEM = (s) => {
   const instructions = userInstructions(s.root)
   return [
-    prompt('agent/system', { root: s.root, files: '', more: '', caller: Boolean(s.appendSystem) }),
+    prompt('agent/system', { root: s.root, env: envLine(), today: new Date().toISOString().slice(0, 10), rootList: rootList(s.root), servers: serversNote(s.root), files: '', more: '', caller: Boolean(s.appendSystem) }),
     instructions && prompt('agent/instructions', { instructions }),
     s.memory && prompt('agent/memory', { tags: s.memory.tagSummary() || '(none yet)' }),
     s.strat.vision && prompt('agent/you-see'), // models that can see often say they can't
@@ -594,13 +613,28 @@ async function runNative(s, task, images, signal) {
     delete s.chat.branchNote
   }
   s.compactedAt = -1
-  // Auto-compact: every 100 messages, the conversation is summarized (what fits each model is
-  // models.dev's business and the model list's: one that fails, the next takes over)
-  const COMPACT_AT = 100
-  const nearlyFull = () => s.autoCompact && s.messages.length >= COMPACT_AT + (s.compactFailedAt ?? 0)
+  // Auto-compact: when the conversation takes 85% of the window of the model answering now (its
+  // window as set up, measured or learned; also when that changes mid-task, or the model list moves
+  // on to a model with a smaller one), so there's room left for the reply. Its size: what the server
+  // counted for this conversation's last request (s.counted) plus the estimate of what came since
+  // (the tool results), or the estimate of all of it when that's more (no count yet: a resumed
+  // session, just compacted). After a failed try: again once it has grown by another 5%.
+  const used = () => {
+    const ratio = strat.ratio ?? 1
+    const all = tokensOf(s.messages, [...TOOL_DEFS, ...extraTools(s)], ratio)
+    const k = s.counted
+    if (!k?.tokens || k.upTo > s.messages.length) return all
+    return Math.max(all, k.tokens + tokensOf(s.messages.slice(k.upTo), null, ratio))
+  }
+  const nearlyFull = () => s.autoCompact && strat.context > 0 && used() >= strat.context * COMPACT_SHARE && used() >= (s.compactFailedAt ?? 0)
+  const fullness = () => `context ${Math.round((used() / strat.context) * 100)}% full (~${kTokens(used())} of ${kTokens(strat.context)})`
+  // Still that full after compacting (what every request carries, the system prompt and the tools'
+  // schemas, takes most of the window): compacting again won't free anything, so not until it has
+  // grown by another 5% (not a summary request at every step).
+  const afterCompact = () => (s.compactFailedAt = used() >= strat.context * COMPACT_SHARE ? used() + Math.round(strat.context * 0.05) : 0)
   // Already that long from earlier messages: compact first, so the new message stays word for word.
   if (nearlyFull()) {
-    await s.compact({ signal }).catch((e) => (e.name === 'AbortError' ? Promise.reject(e) : ui.warn(`could not compact: ${e.message}`)))
+    await s.compact({ signal, why: fullness() }).then(afterCompact, (e) => (e.name === 'AbortError' ? Promise.reject(e) : ui.warn(`could not compact: ${e.message}`)))
   }
   // only the memory notes this message matches go with it (the system prompt has just the tags)
   // each note once per conversation (again if it changed, or after compacting dropped it)
@@ -610,24 +644,36 @@ async function runNative(s, task, images, signal) {
   s.chat.sentNotes = [...sent, ...notes.map(key)]
   const text = notes.length ? `${task}\n\n${prompt('agent/memory-relevant', { notes: notes.map((n) => `[[${n.name}]] — ${n.description}`).join('\n') })}` : task
   const planning = ui.permission === 'plan'
-  const said = planning && !s.isSub ? `${text}\n\n${prompt('agent/plan-mode')}` : text
+  // the research-first reminder: small models follow the user's message far more than the system
+  // prompt (not a helper's job, nor a program's own task with its own instructions)
+  const noted = !s.isSub && !s.appendSystem ? `${text}\n\n${prompt('agent/research-first', { today: new Date().toISOString().slice(0, 10) })}` : text
+  const said = planning && !s.isSub ? `${noted}\n\n${prompt('agent/plan-mode')}` : noted
   const content = images.length ? [{ type: 'text', text: said }, ...images.map((url) => ({ type: 'image_url', image_url: { url } }))] : said
   s.messages.push({ role: 'user', content })
   attachNamed(s, task) // files the message names: as if already read (saves a round trip each)
   // the tools: built again each step (the model answering may change; client.js leaves them out for
   // one that can't call tools)
   const toolList = () => [...TOOL_DEFS, ...extraTools(s)].filter((f) => allowed(s, f.name) && !(planning && PLAN_HIDDEN.has(f.name)) && !(f.name === 'ask_user' && ui.noUser)).map((f) => ({ type: 'function', function: f }))
+  const guard = newGuard() // calls made again with nothing changed: the earlier result instead
   let lastCall = '' // the last call (tool and arguments), and how many times in a row
   let inRow = 0
   // A todo list left done from an earlier message is cleared; an unfinished one stays.
   if (!s.isSub && s.chat.todos?.every((t) => t.status === 'completed')) s.chat.todos = []
   s.todoTouched = false
+  s.task = task // the user's message, for the page review (lookAtUi)
+  s.uiTouched = new Set() // pages (and styles) written in this message: looked at before it ends
+  s.uiLooks = 0
+  s.uiErrorsPrev = [] // hard errors from the last look: when one is gone next look, it was fixed — learn from it
+  s.runFails = new Map() // a command that failed (by its tool) → its error; when the same tool runs clean after an edit, that's a verified fix to learn from (any language, not just web)
+  s.edits = 0 // successful file edits so far this message (to tell a real fix from a lucky rerun)
   let nudged = 0 // reminders sent this message about open todo items or a Stop hook
 
   let empty = 0 // replies in a row with neither text nor tool calls
-  let stuck = null // a tool called the same way five times this message: stop
+  let looping = 0 // replies cut for going into a loop, this message
+  let stuck = null // why it's stopped: going round in circles this message
   let garbled = 0 // replies with a tool call written as text (template markup), this message
   let movedOn = 0 // models given up on for that, in this message
+  let refitted = false // this step's conversation was just compacted for a smaller model the list moved on to
   // No step limit: a long fix takes many steps, and Esc stops it. A caller can set one (--max-turns).
   for (let step = 0; ; step++) {
     const tools = toolList()
@@ -641,25 +687,18 @@ async function runNative(s, task, images, signal) {
       ui.warn(`stopped after ${s.maxTurns} steps (--max-turns); say "continue" to go on`)
       throw Object.assign(new Error(`stopped after ${s.maxTurns} steps (--max-turns)`), { maxTurns: true })
     }
-    // after a failed compaction, the next try waits for 20 more messages
+    // after a failed compaction, the next try waits until the conversation has grown by 5% of the window
     if (nearlyFull() && step !== s.compactedAt) {
       s.compactedAt = step
-      await s.compact({ signal, midTask: true, task }).then(
-        () => (s.compactFailedAt = 0),
+      await s.compact({ signal, midTask: true, task, why: fullness() }).then(
+        afterCompact,
         (e) => {
           if (e.name === 'AbortError') throw e
-          s.compactFailedAt = (s.compactFailedAt ?? 0) + 20
-          log('compact', `failed (${e.message}); trying again 20 messages later`)
+          s.compactFailedAt = used() + Math.round(strat.context * 0.05)
+          log('compact', `failed (${e.message}); trying again once it's ~${s.compactFailedAt} tokens`)
         },
       )
     }
-    // what the user typed while it worked goes in before the next step (steering)
-    const added = step && !s.isSub ? (ui.takeAhead?.() ?? []) : []
-    if (added.length) {
-      for (const l of added) ui.print(`${c.magenta('♥')} ${c.bright(l)}`)
-      log('task', 'the user added while working:', added)
-      s.messages.push({ role: 'user', content: prompt('agent/user-added', { text: added.join('\n\n') }) })
-    }
     // the model answering can change mid-message (your model list): the system prompt follows it
     const now = SYSTEM(s)
     if (s.messages[0]?.content !== now && (s.messages[0]?.role === 'system' || strat.mergeSystem)) s.messages[0] = { ...s.messages[0], content: now }
@@ -672,14 +711,45 @@ async function runNative(s, task, images, signal) {
     // the prompts or HEARTCODE.md changed meanwhile (applySettings): the system prompt again, now
     if (s.refreshSystem && (s.messages[0]?.role === 'system' || strat.mergeSystem)) s.messages[0] = { ...s.messages[0], content: SYSTEM(s) }
     s.refreshSystem = false
-    const res = await client.chat({ messages: s.messages, tools, stream }, { signal, onToken: out.text, onReasoning: out.think, onToolDelta })
+    let res
+    try {
+      res = await client.chat({ messages: s.messages, tools, stream }, { signal, onToken: out.text, onReasoning: out.think, onToolDelta, fit: !refitted })
+    } catch (e) {
+      if (!e.tooBig) throw e
+      // The model list moved on (the one before failed) to a model whose window can't hold the
+      // conversation: compacted for it (by it, to its size), then the same step again. Once: still
+      // too big after that (its window can't even hold the start), it's sent anyway.
+      ui.stopSpin()
+      out.end()
+      log('compact', e.message)
+      refitted = true
+      await s.compact({ signal, midTask: true, task, why: `${client.model} took over and its window is smaller` }).catch((err) => {
+        if (err.name === 'AbortError') throw err
+        log('compact', `failed (${err.message}); sending it anyway`)
+      })
+      step--
+      continue
+    }
+    refitted = false
     ui.stopSpin()
     if (!stream) {
       out.think(res.reasoning)
       out.text(res.content)
     }
     out.end()
+    // the reply went round and round (client.js cut it): told so, and asked again
+    if (res.looped) {
+      if (++looping > 3) {
+        ui.warn(`stopped: ${client.model} keeps going into a loop`)
+        return finalAnswer(s, signal, 'its replies kept going into a loop')
+      }
+      ui.warn(`${client.model} went into a loop; cut, and asked again`)
+      if (res.content.trim()) s.messages.push({ role: 'assistant', content: res.content })
+      s.messages.push({ role: 'user', content: prompt('agent/looped', { sample: res.looped }) })
+      continue
+    }
     s.messages.push({ role: 'assistant', content: res.content || '', ...(res.toolCalls.length && { tool_calls: res.toolCalls }), ...(res.reasoning && res.toolCalls.length && { reasoning_content: res.reasoning }) }) // client.js sends it by the name the provider uses, or not at all
+    s.counted = { tokens: client.lastTokens, upTo: s.messages.length } // the server's count: up to this reply (auto-compact)
     writtenBy.set(s.messages.at(-1), client.model) // its thinking goes back to this model only
     // a tool call written out as text instead of made (some models do, after a long conversation): made
     const leak = !res.toolCalls.length && leakedCall(res.content)
@@ -725,6 +795,12 @@ async function runNative(s, task, images, signal) {
     }
     empty = 0
     if (!res.toolCalls.length) {
+      // a page it built or restyled: HeartCode opens it and shows it the result, to check and fix
+      const look = !s.isSub && (await lookAtUi(s, signal))
+      if (look) {
+        s.messages.push({ role: 'user', content: look })
+        continue
+      }
       const more = nudged < 3 && !s.isSub && (await notDone(s, signal, nudged > 0))
       if (!more) return res.content
       nudged++
@@ -748,6 +824,18 @@ async function runNative(s, task, images, signal) {
       ui.step('agent', clip([args.model && `${args.model}:`, args.description].filter(Boolean).join(' '), 80))
       together.set(call.id, runTool('agent', args, s, signal, call.id))
     }
+    // lookups in one reply (searches, pages, files) run at the same time; the same one twice, once
+    const early = new Map() // call id → { refused } or { running }
+    const bySig = new Map()
+    for (const call of res.toolCalls) {
+      const name = call.function.name
+      const args = argsOf(call)
+      if (!LOOKUPS.has(name) || !args || !allowed(s, name)) continue
+      const sig = `${name} ${JSON.stringify(args)}`
+      const refused = guard.before(name, args)
+      if (refused) early.set(call.id, { refused })
+      else early.set(call.id, { running: bySig.get(sig) ?? bySig.set(sig, runTool(name, args, s, signal, call.id)).get(sig) })
+    }
     for (const call of res.toolCalls) {
       const name = call.function.name
       const args = argsOf(call)
@@ -765,16 +853,22 @@ async function runNative(s, task, images, signal) {
                   ? ''
                   : (args.path ?? args.url ?? args.query ?? args.filter ?? args.name ?? '')
       if (name !== 'run_command' && !together.has(call.id)) ui.step(name, clip(detail, 80))
-      let out = together.has(call.id) ? await together.get(call.id) : !allowed(s, name) ? `error: the tool ${name} is not allowed here` : args ? await runTool(name, args, s, signal, call.id) : 'error: the tool arguments were not valid JSON'
+      const pre = early.get(call.id)
+      const refused = pre ? (pre.refused ?? null) : !together.has(call.id) && args && allowed(s, name) ? guard.before(name, args) : null
+      let out = refused ?? (pre ? await pre.running : together.has(call.id) ? await together.get(call.id) : !allowed(s, name) ? `error: the tool ${name} is not allowed here` : args ? await runTool(name, args, s, signal, call.id) : 'error: the tool arguments were not valid JSON')
+      if (!refused && args) out += guard.after(name, args, out)
+      if (guard.stuck) stuck ??= guard.stuck
+      if (!s.isSub && s.memory && !refused && args) await noteRun(s, name, args, out, signal).catch((e) => log('learn', `run note: ${e.message}`)) // learn from any run that failed then passed
       // the same call again and again in a row (a weak model going round): told at the third, stopped at the fifth
       const sig = `${name} ${call.function.arguments}`
       inRow = sig === lastCall ? inRow + 1 : 1
       lastCall = sig
       if (inRow >= 3) out += `\n\n${prompt('agent/repeating', { n: inRow })}`
-      if (inRow >= 5) stuck = name
+      if (inRow >= 5) stuck = `made the same ${name} call five times in a row`
       if (name === 'read_file' || name === 'search' || name === 'list_files' || name === 'web_fetch' || name === 'web_search') ui.result(`${out.split('\n').length} lines`)
       else if (name === 'agent' && !failed(out)) ui.result(`${s.ui.permission === 'plan' ? 'planned' : 'done'}: ${clip(out.split('\n').find((l) => l.trim()) ?? '', 100)}`)
       else if (failed(out)) ui.result(clip(out, 120))
+      client.refresh?.() // a setting changed while the tool ran (the window): its result is cut by the new one
       const msg = { role: 'tool', tool_call_id: call.id, content: fitResult(s, name, out) }
       if (name === 'read_file' && args && !args.start_line && !args.end_line && !failed(out)) replaceCopy(s, args.path, msg)
       s.messages.push(msg)
@@ -782,8 +876,8 @@ async function runNative(s, task, images, signal) {
     }
     trimOldResults(s)
     if (stuck) {
-      ui.warn(`stopped: ${client.model} made the same ${stuck} call five times in a row`)
-      return finalAnswer(s, signal, `the same ${stuck} call five times`)
+      ui.warn(`stopped: ${client.model} ${stuck}`)
+      return finalAnswer(s, signal, stuck)
     }
     // screenshots from MCP tools: tool results are text only, so images follow as a message
     if (s.pendingImages?.length) {
@@ -793,6 +887,297 @@ async function runNative(s, task, images, signal) {
   }
 }
 
+// One message's calls, so a model going round in circles is caught even when the calls aren't in a
+// row or differ only a little: the same search or page again, the same command, read or search
+// again with nothing changed since (it gets the earlier result back instead), command after command
+// failing. No limit on how much it looks up: new searches and pages always run; only going round
+// (ten calls already made) stops it.
+// before: what to send back instead of running it (the earlier result), or null; after: a note for its result.
+const EDITS = new Set(['edit_file', 'write_file', 'append_file', 'apply_patch'])
+// Tools that only look (nothing changes): several in one reply run at the same time.
+const LOOKUPS = new Set(['web_search', 'web_fetch', 'read_file', 'search', 'list_files', 'find_command', 'lsp'])
+export function newGuard() {
+  const seen = new Map() // what a call is → { out, at }
+  let epoch = 0 // goes up with each change (an edit, a command that can change things)
+  let failing = 0
+  let repeats = 0
+  const g = { stuck: null }
+  const words = (q) => [...new Set(String(q ?? '').toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [])].sort().join(' ')
+  const keyOf = (name, a) => {
+    if (name === 'web_search') return `search: ${words(a.query)}`
+    if (name === 'web_fetch') return `page: ${String(a.url ?? '').toLowerCase().replace(/^https?:\/\/(www\.)?/, '').replace(/\/+$/, '')} @${a.start ?? 0}`
+    if (['run_command', 'read_file', 'search', 'list_files', 'find_command', 'lsp'].includes(name)) return `${name} ${JSON.stringify(a)} @${epoch}`
+    return null
+  }
+  g.before = (name, a) => {
+    const k = keyOf(name, a)
+    const was = k && seen.get(k)
+    // a command may be waited on (a server starting): the same one again after a while runs
+    if (!was || (name === 'run_command' && Date.now() - was.at > 20_000)) return null
+    repeats++
+    if (repeats >= 10) g.stuck = 'kept making calls it had already made (10 repeats)' // going round, not finding anything new
+    return prompt('agent/already-done', { result: was.out }) + (repeats >= 3 ? `\n\n${prompt('agent/circling')}` : '')
+  }
+  g.after = (name, a, out) => {
+    let note = ''
+    if (name === 'run_command') {
+      const code = Number(/^exit code (-?\d+)/.exec(out)?.[1] ?? 0)
+      failing = code ? failing + 1 : 0
+      if (failing >= 4) note += `\n\n${prompt('agent/failing-in-row', { n: failing })}`
+      if (failing >= 8) g.stuck = 'had eight commands in a row fail'
+      if (!readOnlyCommand(String(a.command ?? ''))) epoch++ // it may have changed things: what came before can be done again
+    }
+    if (EDITS.has(name) && !failed(out)) epoch++
+    const k = keyOf(name, a) // after the command's own change: the same again right away is the same
+    if (k) seen.set(k, { out: clip(String(out), 6000), at: Date.now() })
+    return note
+  }
+  return g
+}
+
+// The pages this message wrote or restyled (an .html written, or one using a .css written),
+// opened in the built-in browser (chrome-devtools): a screenshot at desktop width (the whole page)
+// and at phone width, given to the model to check against its brief and fix. Twice per message at
+// most; nothing when there's no browser. A model that can't see gets them described by one of
+// yours that can.
+// Problems found in a built page without a browser: JavaScript that doesn't parse, and the Tailwind
+// CDN used with @apply/@layer (it throws "Cannot apply unknown utility class" at runtime and the
+// styling breaks). These are caught even when the browser can't be opened.
+function staticChecks(root, rel) {
+  const out = []
+  let html
+  try {
+    html = fs.readFileSync(path.join(root, rel), 'utf8')
+  } catch {
+    return out
+  }
+  for (const m of html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
+    const attrs = m[1]
+    if (/\bsrc\s*=/.test(attrs) || /\btype\s*=\s*["']?module/.test(attrs) || !m[2].trim()) continue // external or ESM: can't check this way
+    try {
+      new Function(m[2]) // compiles without running: throws on a syntax error (unclosed brace, typo)
+    } catch (e) {
+      out.push(`${rel}: the <script> doesn't parse — ${e.message}. The page's JavaScript won't run at all. Find and fix it (often an unclosed brace or bracket).`)
+    }
+  }
+  const tailwindCdn = /cdn\.tailwindcss\.com|@tailwindcss\/browser|type\s*=\s*["']text\/tailwindcss/.test(html)
+  if (tailwindCdn) {
+    const css = [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1]).join('\n')
+    const defined = new Set([...css.matchAll(/(?:^|\})\s*\.([a-zA-Z][\w-]*)\s*\{/g)].map((m) => m[1])) // classes defined with a rule
+    const applied = new Set([...css.matchAll(/@apply\b([^;}{]*)/g)].flatMap((m) => m[1].split(/\s+/).map((t) => t.replace(/[^\w-].*$/, '')).filter(Boolean)))
+    const bad = [...applied].filter((c) => defined.has(c))
+    if (bad.length) out.push(`${rel}: the Tailwind browser build (CDN) throws "Cannot apply unknown utility class" here — you @apply a class you defined yourself (${bad.join(', ')}), which only a real build step allows. Put those utility classes directly in the HTML (class="…"), not behind @apply; or drop the @apply and write the rules in plain CSS.`)
+  }
+  return out
+}
+
+// The tech a mistake is about, for tagging a lesson so it's recalled on later tasks of the same
+// kind. Reads both the error and the command/file it came from; works for any language, not just web.
+function techOf(context) {
+  const t = String(context).toLowerCase()
+  const tags = []
+  const add = (re, tag) => re.test(t) && tags.push(tag)
+  add(/tailwind/, 'tailwind')
+  add(/\btsc?\b|\.tsx?\b|typescript|ts-node/, 'typescript')
+  add(/\bnode\b|\.c?js\b|\.mjs\b|javascript|npm|pnpm|yarn|\bbun\b|vite|webpack|eslint|referenceerror|is not defined/, 'javascript')
+  add(/\breact\b|usestate|useeffect|\bjsx\b|next\.?js/, 'react')
+  add(/\bpython3?\b|\bpip3?\b|\bpytest\b|\buv\b|\.py\b|traceback|modulenotfound|indentationerror/, 'python')
+  add(/\bgo\b|\.go\b|golang|go\.mod/, 'go')
+  add(/\bcargo\b|\brustc\b|\.rs\b|rust/, 'rust')
+  add(/\bjava\b|\bmvn\b|gradle|\.java\b/, 'java')
+  add(/\bruby\b|\bgem\b|bundle|\.rb\b|rails/, 'ruby')
+  add(/\bphp\b|composer|\.php\b|laravel/, 'php')
+  add(/\bmake\b|cmake|\bgcc\b|clang|\.c\b|\.cpp\b/, 'c')
+  add(/\bdocker\b|dockerfile|kubectl|\bk8s\b/, 'docker')
+  add(/\bcurl\b|\bwget\b|http|endpoint|\bapi\b|\bfetch\b/, 'api')
+  add(/\.html\b|<script|<style|\bdom\b/, 'html')
+  add(/\.css\b|@apply|@layer|utility class|stylesheet/, 'css')
+  add(/\bsql\b|postgres|sqlite|mysql|database/, 'sql')
+  return tags.length ? [...new Set(tags)].slice(0, 4) : ['general']
+}
+
+// A command's tool: its first word (npm, python3, go, cargo, make, curl…), paths and flags dropped,
+// so the same kind of command failing then passing is recognised across runs.
+const runTool_ = (cmd) => (String(cmd).trim().match(/^[\w./-]+/)?.[0] ?? '').split('/').pop()
+
+// After a command: a failure (non-zero exit, or a tool error) is remembered by its tool; a later
+// clean run of the same tool, once files were edited, means it was fixed — learn from it. This is
+// how HeartCode learns from anything it runs, in any language, not only web pages.
+async function noteRun(s, name, args, out, signal) {
+  if (name === 'edit_file' || name === 'write_file' || name === 'apply_patch') {
+    if (!failed(out) && !/error:/i.test(out.slice(0, 40))) s.edits++
+    return
+  }
+  if (name !== 'run_command') return
+  const tool = runTool_(args.command)
+  if (!tool) return
+  const code = Number(/^exit code (-?\d+)/.exec(out)?.[1] ?? (failed(out) ? 1 : 0))
+  const bad = code !== 0 || /\b(error|traceback|exception|failed|cannot|not found|undefined)\b/i.test(out.split('\n').slice(0, 6).join(' '))
+  if (bad) {
+    const line = out.split('\n').find((l) => /\b(error|traceback|exception|failed|cannot|not found)\b/i.test(l)) ?? out.split('\n').find((l) => l.trim()) ?? ''
+    s.runFails.set(tool, { error: `${args.command.split(/\s+/)[0]}: ${line.trim().slice(0, 160)}`, atEdits: s.edits, cmd: args.command })
+    return
+  }
+  // a clean run: did this tool fail earlier, and have files been edited since? then it's a real fix
+  const prev = s.runFails.get(tool)
+  if (prev && s.edits > prev.atEdits) {
+    s.runFails.delete(tool)
+    await learnFromFixes(s, [{ error: prev.error, context: `${prev.cmd} ${prev.error}` }], signal)
+  }
+}
+
+// Turn each fixed mistake into one reusable rule and save it (global memory, tagged by tech). The
+// model writes the rule from the error; a near-duplicate lesson is skipped. Recall is automatic
+// (memory.relevant attaches matching notes to a later message).
+async function learnFromFixes(s, fixed, signal) {
+  for (const { error, context } of fixed.slice(0, 5)) {
+    const tags = techOf(context ?? error)
+    const near = s.memory.search(`tag:lesson ${tags.join(' ')}`).find((n) => n.body.toLowerCase().includes(error.replace(/^[^:]*:\s*/, '').toLowerCase().slice(0, 30)))
+    if (near) continue // already learned
+    let rule = ''
+    try {
+      rule = (await s.client.chat({ messages: [{ role: 'user', content: prompt('agent/lesson', { error }) }] }, { signal })).content.trim().split('\n')[0].replace(/^["'\s-]+|["']+$/g, '').slice(0, 200)
+    } catch {}
+    if (!rule || rule.length < 10) rule = error.replace(/^[^:]*:\s*/, '') // the model couldn't phrase it: keep the error's own wording
+    const name = s.memory.write({ description: rule, type: 'reference', tags: ['lesson', ...tags], content: `${rule}\n\nLearned after this was caught and fixed while building: ${error}`, scope: 'global' })
+    s.ui.step('learned', rule.slice(0, 90))
+    log('learn', `saved lesson [[${name}]] (#${tags.join(' #')}): ${rule}`)
+  }
+}
+
+// Injected into the page (evaluate_script): fills inputs, clicks buttons, toggles checkboxes, and
+// returns the errors any of them threw. Navigation is blocked so one click can't end the test.
+const SMOKE_TEST = `async () => {
+  const errs = []
+  const push = (m) => { const s = String(m && m.message ? m.message : m).slice(0, 180); if (s && !errs.includes(s)) errs.push(s) }
+  addEventListener('error', (e) => push(e.message || (e.error && e.error.message) || e), true)
+  addEventListener('unhandledrejection', (e) => push('unhandled: ' + ((e.reason && e.reason.message) || e.reason)), true)
+  const ce = console.error; console.error = (...a) => { push(a.map(String).join(' ')); ce.apply(console, a) }
+  document.addEventListener('submit', (e) => e.preventDefault(), true)
+  document.addEventListener('click', (e) => { const a = e.target.closest && e.target.closest('a'); const h = a && a.getAttribute('href'); if (h && h[0] !== '#') e.preventDefault() }, true)
+  for (const inp of document.querySelectorAll('input:not([type=button]):not([type=submit]):not([type=checkbox]):not([type=radio]):not([type=file]), textarea')) {
+    try { inp.focus(); inp.value = 'Test 123'; inp.dispatchEvent(new Event('input', { bubbles: true })); inp.dispatchEvent(new Event('change', { bubbles: true })); for (const t of ['keydown','keypress','keyup']) inp.dispatchEvent(new KeyboardEvent(t, { key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true })) } catch (e) { push('typing: ' + e.message) }
+  }
+  const btns = [...document.querySelectorAll('button, [role=button], input[type=button], input[type=submit], a[href^="#"], a:not([href]), [onclick]')]
+  let controls = btns.length
+  for (const el of btns.slice(0, 30)) { try { el.click() } catch (e) { push('click "' + ((el.textContent || el.getAttribute('aria-label') || el.value || '').trim().slice(0, 30)) + '": ' + e.message) } ; await new Promise((r) => setTimeout(r, 10)) }
+  for (const cb of document.querySelectorAll('input[type=checkbox], input[type=radio]')) { controls++; try { cb.click() } catch (e) { push('toggle: ' + e.message) } }
+  await new Promise((r) => setTimeout(r, 200))
+  return JSON.stringify({ errors: errs, controls })
+}`
+
+async function lookAtUi(s, signal) {
+  if (!s.uiTouched?.size || s.uiLooks >= 3 || s.ui.permission === 'plan') return null
+  const touched = [...s.uiTouched]
+  s.uiTouched.clear()
+  const styles = touched.filter((f) => /\.css$/i.test(f)).map((f) => path.basename(f))
+  const pages = touched.filter((f) => /\.html?$/i.test(f))
+  if (styles.length) {
+    for (const f of listFiles(s.root).filter((f) => /\.html?$/i.test(f))) {
+      try {
+        if (styles.some((c) => fs.readFileSync(path.join(s.root, f), 'utf8').includes(c))) pages.push(f)
+      } catch {}
+    }
+  }
+  const shown = [...new Set(pages)].filter((f) => fs.existsSync(path.join(s.root, f))).slice(0, 2)
+  if (!shown.length) return null
+  s.uiLooks++
+  const browser = s.mcp?.get?.('chrome-devtools')
+  const errors = shown.flatMap((rel) => staticChecks(s.root, rel)) // works with no browser
+  const shots = []
+  let opened = 0 // pages actually opened in the browser (0: couldn't verify it runs)
+  const text = (r) => (r.content ?? []).map((p) => p.text ?? '').join('\n')
+  const done = browser ? await s.mcpGate?.() : null
+  try {
+    if (!browser) throw new Error('no browser')
+    for (const rel of shown) {
+      s.ui.spinner(`opening ${rel} in the browser`)
+      const openedText = text(await browser.call('new_page', { url: pathToFileURL(path.join(s.root, rel)).href }, signal))
+      opened++
+      const id = Number(/(\d+):[^\n]*\[selected\]/.exec(openedText)?.[1]) || undefined // newer versions number the pages
+      const page = id ? { pageId: id } : {}
+      await new Promise((r) => setTimeout(r, 600)) // the scripts run before we read the console
+      const con = await browser.call('list_console_messages', page, signal).catch(() => null)
+      for (const line of (con ? text(con) : '').split('\n')) {
+        if (!/\[error\]/i.test(line) || /favicon\.ico/i.test(line)) continue // a missing favicon isn't a real problem
+        errors.push(`${rel}: ${line.replace(/^\s*msgid=\d+\s*\[error\]\s*/i, '').replace(/\s*\(\d+ args?\)\s*$/, '').trim()}`)
+      }
+      // Drive it like a user: fill the inputs, click every button, toggle every checkbox. An error a
+      // control throws means it doesn't work (a dead button, a popup that fails) — caught here, not on a plain load.
+      s.ui.spinner(`testing ${rel} (clicking through it)`)
+      const ran = await browser.call('evaluate_script', { ...page, function: SMOKE_TEST }, signal).catch((e) => (log('look', `smoke test failed on ${rel}: ${e.message}`), null))
+      const blob = ran && /\{"errors":\s*\[[\s\S]*?\],\s*"controls":\s*\d+\}/.exec(text(ran).replace(/\\n/g, ' ').replace(/\\"/g, '"').replace(/\\\\/g, '\\'))
+      if (blob) {
+        try {
+          const r = JSON.parse(blob[0])
+          for (const err of r.errors.slice(0, 8)) errors.push(`${rel}: a control is broken — ${err}`)
+          log('look', `${rel}: exercised ${r.controls} control(s), ${r.errors.length} broke`)
+        } catch (e) {
+          log('look', `smoke parse: ${e.message}`)
+        }
+      }
+      for (const [width, height, fullPage] of [[1280, 900, true], [390, 844, false]]) {
+        await browser.call('resize_page', { ...page, width, height }, signal)
+        const r = await browser.call('take_screenshot', { ...page, ...(fullPage && { fullPage }) }, signal)
+        const img = r.content?.find((p) => p.type === 'image' && p.data)
+        if (img) shots.push({ label: `${rel} at ${width} px wide${fullPage ? ' (the whole page)' : ''}`, url: `data:${img.mimeType ?? 'image/png'};base64,${img.data}` })
+      }
+      if (id) await browser.call('close_page', page, signal).catch(() => {})
+    }
+  } catch (e) {
+    if (signal?.aborted) throw e
+    log('look', `couldn't open ${shown.join(', ')} in the browser: ${e.message}`)
+  } finally {
+    done?.()
+    s.ui.stopSpin()
+  }
+  if (errors.length) log('look', `problems found: ${errors.join(' | ')}`)
+  // Learn: a hard error that was there last look and is gone now was fixed — save the lesson so it
+  // isn't made again (recalled on later tasks about the same tech). Only in the main agent.
+  if (!s.isSub && s.memory) {
+    const key = (e) => e.replace(/^[^:]*:\s*/, '').toLowerCase().replace(/["'`]/g, '').replace(/\d+/g, '#').replace(/\s+/g, ' ').trim().slice(0, 120)
+    const nowKeys = new Set(errors.map(key))
+    const fixed = (s.uiErrorsPrev ?? []).filter((p) => !nowKeys.has(p.key))
+    if (fixed.length) await learnFromFixes(s, fixed, signal).catch((e) => log('learn', `failed: ${e.message}`))
+    s.uiErrorsPrev = errors.map((e) => ({ key: key(e), error: e }))
+  }
+  // Couldn't open it in a browser (none configured, or it failed): don't pass silently — the model
+  // must verify it itself. Static checks still apply.
+  const unverified = opened === 0 ? `${shown.join(', ')} could not be opened in a browser here, so HeartCode could not confirm it works. Before you finish, verify it yourself: open it and check it actually works — no errors in the console, every button and interaction does what it should.` : ''
+  // JavaScript errors mean the page is broken however good it looks: fed back on their own (text,
+  // no model that sees needed), and the visual review added when there is one.
+  const brokenList = errors.length ? errors.map((e, i) => `${i + 1}. ${e}`).join('\n') : ''
+  let found = ''
+  if (shots.length) {
+    log('look', shots.map((x) => x.label))
+    // reviewed in a request of its own (the screenshots and the user's request, nothing else): a
+    // model checking its own work in its own conversation tends to call it fine
+    const self = { provider: s.client.provider, model: s.client.model, images: s.strat.vision }
+    const reviewers = [...(self.images ? [self] : []), ...(s.team?.() ?? []).filter((t) => t.images && !(t.provider === self.provider && t.model === self.model))]
+    const ask = prompt('agent/ui-review', { task: s.task ?? '', shots: shots.map((x, i) => `${i + 1}. ${x.label}`).join('\n') })
+    for (const t of reviewers) {
+      s.ui.spinner(`${t.model} is reviewing ${shown.join(', ')}`)
+      try {
+        const { client } = t === self ? { client: s.client } : await s.engineFor(t)
+        found = (await client.chat({ messages: [{ role: 'user', content: [{ type: 'text', text: ask }, ...shots.map((x) => ({ type: 'image_url', image_url: { url: x.url } }))] }] }, { signal })).content.trim()
+        if (found) break
+      } catch (e) {
+        if (signal?.aborted) throw e
+        log('look', `${t.model} couldn't review: ${e.message}`)
+      }
+    }
+    s.ui.stopSpin()
+  }
+  const visual = found && !(/^\W*none\W*$/i.test(found) || !/\d+[.)]\s/.test(found)) ? found : ''
+  if (!brokenList && !visual && !unverified) {
+    if (shots.length) s.ui.step('look', `${shown.join(', ')}: works, nothing to fix`)
+    return null
+  }
+  s.ui.step('look', `${shown.join(', ')}: ${[errors.length && `${errors.length} problem${errors.length > 1 ? 's' : ''}`, visual && 'review notes', unverified && 'verify it yourself'].filter(Boolean).join(', ')}`)
+  const problems = [brokenList, visual, unverified].filter(Boolean).join('\n')
+  return prompt('agent/look-at-ui', { files: shown.join(', '), problems })
+}
+
 // The model says it's done: is it? Not while its todo list (from this message) has open items, or
 // while a Stop hook says otherwise. Returns what to tell it, or null. Each is asked a few times at
 // most (the caller counts), so a model that can't finish still ends.
@@ -820,8 +1205,7 @@ function helperUI(ui, label) {
       text() {},
       end() {
         if (!thought.trim()) return
-        const secs = ((Date.now() - t0) / 1000).toFixed(1)
-        ui.print(c.faint(c.italic(`  ✻ ${label} thought for ${secs}s`)) + (ui.showThinking ? `\n${c.think(c.italic(thought.trim().replace(/^/gm, '    ')))}` : ''))
+        ui.print(c.faint(c.italic(`  ✻ ${label} thought for ${duration(Date.now() - t0)}`)) + (ui.showThinking ? `\n${c.think(c.italic(thought.trim().replace(/^/gm, '    ')))}` : ''))
       },
     }
   }