heartcode 0.1.0 → 0.1.1

package/src/headless.js

@@ -12,14 +12,14 @@
 // told to the model. Logs and warnings go to stderr (and HEART_LOG), never stdout.
 import readline from 'node:readline'
 import { log } from './log.js'
-import { clip, TOOL_DEFS, extraTools } from './tools.js'
+import { clip, TOOL_DEFS, extraTools, loadMcpTools } from './tools.js'
 import { allowed } from './agent.js'
 
 // Claude Code's tool names → HeartCode's (for --allowedTools / --disallowedTools).
 const CLAUDE_TOOLS = { Read: 'read_file', Grep: 'search', Glob: 'list_files', LS: 'list_files', Edit: 'edit_file', MultiEdit: 'edit_file', Write: 'write_file', NotebookEdit: 'edit_file', Bash: 'run_command' }
 export function toolNames(list) {
   const names = list.flatMap((x) => String(x).split(/[,\s]+/)).filter(Boolean).map((t) => t.replace(/\(.*$/, '')) // ponytail: "Bash(git:*)" allows every command, not just git
-  return new Set(names.map((t) => (t.startsWith('mcp__') ? 'mcp' : (CLAUDE_TOOLS[t] ?? t))))
+  return new Set(names.map((t) => CLAUDE_TOOLS[t] ?? t)) // mcp__server__tool and mcp__server as they are (tools.js allowed)
 }
 
 // --permission-mode, in HeartCode's terms or Claude Code's.
@@ -119,8 +119,9 @@ export async function runHeadless(app, opts) {
         emit({ type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: e.id, content: e.output, is_error: e.output.startsWith('error') }] }, session_id })
       }
     }
+    if (s.strat.actions === 'tools' && s.mcp?.names.length) await loadMcpTools(s) // their tools are in the list, as in Claude Code's
     const tools = s.strat.actions === 'tools' ? [...TOOL_DEFS, ...extraTools(s)].map((f) => f.name).filter((n) => allowed(s, n)) : []
-    emit({ type: 'system', subtype: 'init', session_id, model, cwd: app.root, tools, mcp_servers: app.mcp.names.map((name) => ({ name, status: 'pending' })), permissionMode: app.ui.permission, apiKeySource: 'none' })
+    emit({ type: 'system', subtype: 'init', session_id, model, cwd: app.root, tools, mcp_servers: app.mcp.names.map((name) => ({ name, status: s.mcpCatalog?.has(name) ? 'connected' : 'pending' })), permissionMode: app.ui.permission, apiKeySource: 'none' })
   }
 
   let current = null // the message running now: { ctl }

package/src/mcp.js

@@ -5,11 +5,15 @@
 // A local server talks over its stdin/stdout, one message per line. A remote one over Streamable
 // HTTP (or the older HTTP+SSE: "type": "sse", a URL ending in /sse, or when HTTP is refused), and
 // signs in with OAuth when it asks (oauth.js). ${VAR} in a URL or header is the environment's VAR.
-// A server starts the first time the model uses it, and stops when HeartCode exits.
+// A server's tools are offered to the model as tools of their own (mcp__server__tool), from the
+// list it gave the last time it ran (kept in ~/.heart/mcp-tools.json, with its instructions): so a
+// server starts the first time the model uses it, or once to say its tools; it stops when
+// HeartCode exits.
 import { spawn } from 'node:child_process'
+import crypto from 'node:crypto'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { HOME, readJson, readConfig } from './config.js'
+import { HOME, readJson, readConfig, writeJson, VERSION } from './config.js'
 import { log } from './log.js'
 import { savedToken, signIn } from './oauth.js'
 
@@ -75,7 +79,7 @@ class Server {
 
   start(signal) {
     this.ready ??= (async () => {
-      const init = () => this.request('initialize', { protocolVersion: '2025-06-18', capabilities: { roots: {} }, clientInfo: { name: 'heartcode', version: '0.1.0' } }, this.url ? 600_000 : 120_000, signal) // remote: time to sign in
+      const init = () => this.request('initialize', { protocolVersion: '2025-06-18', capabilities: { roots: {} }, clientInfo: { name: 'heartcode', version: VERSION } }, this.url ? 600_000 : 120_000, signal) // remote: time to sign in
       let r
       if (this.url) {
         const type = this.cfg.type ?? this.cfg.transport
@@ -102,6 +106,7 @@ class Server {
         }
       } else r = await this.#spawn(init)
       this.protocol = r?.protocolVersion
+      this.instructions = typeof r?.instructions === 'string' ? r.instructions.trim() : ''
       this.#send({ jsonrpc: '2.0', method: 'notifications/initialized' })
     })().catch((e) => {
       this.stop() // failed to start: the next use tries again
@@ -276,12 +281,14 @@ class Server {
         this.tools.push(...(r.tools ?? []))
         cursor = r.nextCursor
       } while (cursor)
+      this.hub.remember(this)
     }
     return this.tools
   }
 
   async call(tool, args, signal) {
     await this.start(signal)
+    if (!this.tools) this.listTools().catch(() => {}) // started from the saved list: what it has now, for next time
     return this.request('tools/call', { name: tool, arguments: args ?? {} }, 300_000, signal)
   }
 
@@ -301,6 +308,9 @@ class Server {
   }
 }
 
+const TOOLS_FILE = path.join(HOME, 'mcp-tools.json')
+const keyOf = (cfg) => crypto.createHash('sha256').update(JSON.stringify(cfg)).digest('hex').slice(0, 16)
+
 // All configured servers for a project; nothing runs until a server is first used.
 // onSignIn(name, url): set by the screen, to show a remote server's sign-in page (none headless).
 export class Mcp {
@@ -324,6 +334,42 @@ export class Mcp {
     return this.servers.get(name)
   }
 
+  // Each server's { tools, instructions }, for the model: the list saved the last time it ran
+  // (with the same config), else asked for now, waiting at most `wait` ms; a server that hasn't
+  // answered by then (it may still be starting: npx downloads it the first time) or failed to
+  // start isn't in the result. It's tried again next time, and its list is saved once it answers.
+  async catalog(signal, wait = 15_000) {
+    const saved = readJson(TOOLS_FILE, {})
+    const out = new Map()
+    const asks = []
+    for (const [name, sv] of this.servers) {
+      const hit = sv.tools ? { tools: sv.tools, instructions: sv.instructions ?? '' } : saved[name]?.key === keyOf(sv.cfg) ? saved[name] : null
+      if (hit) out.set(name, { tools: hit.tools, instructions: hit.instructions ?? '' })
+      else if (!sv.failed) asks.push(sv.listTools(signal).then((tools) => out.set(name, { tools, instructions: sv.instructions ?? '' }), (e) => {
+        if (e.name === 'AbortError') return
+        sv.failed = true // not waited for again in this run; still usable through the mcp tool
+        log('mcp', `${name}: could not list its tools: ${e.message}`)
+      }))
+    }
+    if (asks.length) {
+      let timer
+      await Promise.race([Promise.all(asks), new Promise((r) => (timer = setTimeout(r, wait)))])
+      clearTimeout(timer)
+    }
+    return out
+  }
+
+  // A server's tools, saved for the next run (the config's hash, not the config: it may hold keys).
+  remember(sv) {
+    const saved = readJson(TOOLS_FILE, {})
+    saved[sv.name] = { key: keyOf(sv.cfg), tools: sv.tools, instructions: sv.instructions ?? '', at: new Date().toISOString() }
+    try {
+      writeJson(TOOLS_FILE, saved)
+    } catch (e) {
+      log('mcp', `could not save ${sv.name}'s tools: ${e.message}`)
+    }
+  }
+
   stopAll() {
     for (const s of this.servers.values()) s.stop()
   }

package/src/prompts.js

@@ -9,9 +9,10 @@
 //   <!-- … -->                             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 = new URL('../prompts/', import.meta.url).pathname
+const BUILTIN = fileURLToPath(new URL('../prompts/', import.meta.url))
 let project = null
 const cache = new Map()
 

package/src/settings.html

@@ -145,7 +145,7 @@
 
   /* Providers & models: every provider's models on the left (pick one), yours in order on the right;
      both fill the screen's height and scroll inside */
-  .work { display: grid; grid-template-columns: minmax(0, 1fr) 420px; gap: 20px; }
+  .work { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 20px; } /* the catalog and your models, half and half */
   .work > .card { padding: 0; display: flex; flex-direction: column; min-height: 0; overflow: hidden; }
   .cat-top { padding: 14px 16px; border-bottom: 1px solid var(--line); display: flex; gap: 8px; align-items: center; }
   .cat-top input { flex: 1; min-width: 0; }
@@ -206,10 +206,10 @@
   .cat-note { padding: 12px 16px; color: var(--muted); font-size: 12.5px; }
   .byname { display: flex; gap: 8px; align-items: center; padding: 10px 16px; border-bottom: 1px solid var(--line); }
   .byname input { height: 32px; font-family: var(--mono); font-size: 12.5px; }
-  /* two lines' room, never more: a test's progress doesn't move the cards below */
-  .olist .test { font-size: 11.5px; line-height: 1.45; margin-top: 3px; color: var(--faint); display: flex; align-items: flex-start; gap: 6px; height: calc(2 * 1.45em + 2px); }
-  .olist .test .msg { flex: 1; min-width: 0; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; overflow-wrap: anywhere; }
-  .olist .test .spin { margin-top: 3px; flex: none; }
+  /* one line: what models.dev says (cut short, all of it on hover), its buttons on the right */
+  .olist .test { font-size: 12px; color: var(--faint); display: flex; align-items: center; gap: 6px; min-width: 0; }
+  .olist .test .msg { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .olist .test .spin { flex: none; }
   .olist .test button { flex: none; }
   .olist .test.ok { color: var(--ok); }
   .olist .test.warn { color: var(--accent); }
@@ -224,13 +224,16 @@
   .spin { width: 10px; height: 10px; border: 2px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: spin .8s linear infinite; }
   @keyframes spin { to { transform: rotate(360deg); } }
   .mine-top { padding: 16px 18px 6px; }
-  .mine-title { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+  .mine-title { display: flex; align-items: center; justify-content: space-between; gap: 6px 8px; flex-wrap: wrap; }
   .mine-title h2 { margin: 0 0 6px; flex: 1; white-space: nowrap; }
   .mine-title button { white-space: nowrap; }
-  .olist { list-style: none; margin: 0; padding: 6px 12px 12px; flex: 1; overflow-y: auto; }
-  .olist li { display: flex; align-items: center; gap: 8px; padding: 9px 10px; border: 1px solid var(--line); border-radius: 10px; margin-bottom: 8px; background: var(--panel); }
-  .olist li.in { border-color: var(--brand); background: var(--brand-soft); }
-  .olist li.next { border-style: dashed; background: none; color: var(--faint); font-size: 12.5px; justify-content: center; padding: 14px 10px; }
+  /* your models as a table: a header, then one line a model */
+  .ohead, .olist li.in { display: grid; grid-template-columns: 14px 30px minmax(0, 1.7fr) minmax(0, 0.6fr) minmax(0, 1.5fr) 26px; align-items: center; column-gap: 8px; padding: 7px 16px; }
+  .ohead { font-size: 12px; color: var(--muted); border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); padding-top: 8px; padding-bottom: 8px; }
+  .olist { list-style: none; margin: 0; padding: 0; flex: 1; overflow-y: auto; }
+  .olist li { border-bottom: 1px solid var(--line); background: var(--panel); font-size: 13px; }
+  .olist li.in:first-child { background: var(--brand-soft); }
+  .olist li.next { border-bottom: 0; background: none; color: var(--faint); font-size: 12.5px; text-align: center; padding: 14px 10px; }
   .olist li.in { cursor: grab; user-select: none; transition: transform .16s ease, box-shadow .16s ease; position: relative; }
   .olist.sorting li.in { transition: transform .16s ease; }
   .olist li.in.lifted { transition: none; z-index: 2; cursor: grabbing; box-shadow: 0 10px 28px rgba(0, 0, 0, .35), 0 0 0 2px var(--brand); }
@@ -243,8 +246,8 @@
   .mt-top .chip { display: inline-flex; align-items: center; gap: 4px; border: 1px solid var(--brand); background: var(--brand-soft); border-radius: 999px; padding: 1px 4px 1px 9px; margin: 2px 4px 2px 0; color: var(--text); font-size: 12.5px; }
   .mt-top .chip button { border: 0; background: none; padding: 0 4px; font-size: 12px; color: var(--muted); }
   .mt-scroll { overflow-x: auto; }
-  .mt { min-width: 1080px; }
-  .mt-h, .mtable li { display: grid; grid-template-columns: 16px 30px minmax(170px, 3fr) minmax(80px, 1.2fr) 76px 82px 56px 62px 54px 60px 64px minmax(200px, 2fr) 30px; align-items: center; column-gap: 8px; padding: 8px 18px; }
+  .mt { min-width: 1090px; }
+  .mt-h, .mtable li { display: grid; grid-template-columns: 16px 28px minmax(150px, 3fr) minmax(70px, 1.1fr) 66px 66px 42px 60px 50px 54px 60px minmax(166px, 1.5fr) minmax(120px, 1.3fr) 28px; align-items: center; column-gap: 6px; padding: 8px 16px; }
   .mt-h { border-bottom: 1px solid var(--line); font-size: 12px; color: var(--muted); padding-top: 10px; padding-bottom: 10px; }
   .mt-h button { border: 0; background: none; padding: 0; font: inherit; color: inherit; text-align: left; white-space: nowrap; }
   .mt-h button:hover { color: var(--text); }
@@ -266,13 +269,19 @@
   .mtable .src { font-size: 12px; color: var(--muted); display: flex; align-items: center; gap: 6px; white-space: nowrap; }
   .mtable .src.warn { color: var(--accent); }
   .mtable button { padding: 1px 7px; font-size: 11.5px; }
+  .mtable .try { font-size: 12px; color: var(--faint); display: flex; align-items: center; gap: 6px; min-width: 0; }
+  .mtable .try .msg { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .mtable .try.ok { color: var(--ok); }
+  .mtable .try.bad { color: var(--err); }
+  .mtable .try.going { color: var(--accent); }
   .mt-empty { padding: 28px 18px; color: var(--muted); }
   .olist .grip { cursor: grab; color: var(--faint); padding: 0 2px; user-select: none; }
   .olist .n { font-weight: 800; color: var(--brand); min-width: 24px; }
-  .olist .what { flex: 1; min-width: 0; }
-  .olist .m { font-family: var(--mono); font-size: 12.5px; font-weight: 600; overflow-wrap: anywhere; }
-  .olist .p { color: var(--muted); font-size: 12px; }
+  .olist .m { font-family: var(--mono); font-size: 12.5px; font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .olist .p { color: var(--muted); font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .olist .p.use { color: var(--brand); font-weight: 600; }
   .olist button { padding: 2px 8px; font-size: 12px; }
+  .olist button.danger { padding: 1px 6px; }
   .mine-rules { border-top: 1px solid var(--line); padding: 4px 18px 16px; }
   .mine-rules .hint { min-height: 2.9em; } /* the hints differ in length: the next setting stays put */
   .mine-empty { padding: 30px 22px; text-align: center; color: var(--muted); }
@@ -796,9 +805,75 @@ function testLine(t) {
   const edit = (label) => h('button', { className: 'small', textContent: label, onclick: (e) => (e.stopPropagation(), openSetup(t)) })
   const [cls, text, action] =
     !x ? ['none', 'looking it up in models.dev…', null]
-      : x.source === 'assumed' ? ['warn', 'not in models.dev: set up what it can do', [retry(t), edit('Set it up')]]
+      : x.source === 'assumed' ? ['warn', 'not in models.dev', edit('Set up')] // its Retry: on the Your models page, and Retry all
       : ['ok', `✓ ${testedText(x)} · ${Object.keys(x.set ?? {}).length ? 'yours' : FROM[x.source]}`, edit('Edit')]
-  return h('div', { className: 'test ' + cls }, h('span', { className: 'msg', textContent: text }), action)
+  const about = x?.source === 'assumed' ? "not in models.dev: Retry, or set up what it can do" : text
+  return h('div', { className: 'test ' + cls }, h('span', { className: 'msg', textContent: text, title: about }), action)
+}
+
+// Test: one short message to the model, to see that it really answers (the key, access to it, its
+// name, the server). The result stays under it until the page is reloaded.
+const TRIES = {} // "provider/model" → { going } | { ok, ms, reply } | { ok: false, error }
+const keyOf = (t) => `${t.provider}/${t.model}`
+// The Works? cell: the last result (cut short, all of it on hover) and Test.
+function triedCell(t) {
+  const r = TRIES[keyOf(t)]
+  const secs = r?.ms != null ? ` · ${(r.ms / 1000).toFixed(1)}s` : ''
+  const [cls, text, about] = !r ? ['', 'not tested', 'send it a short message to see that it really answers (your key, access to it, its name)']
+    : r.going ? ['going', 'testing…', 'sending it a short message']
+    : r.ok ? ['ok', `✓ ${(r.ms / 1000).toFixed(1)}s`, `works: it answered "${r.reply}"${secs}`]
+    : ['bad', `✗ ${r.status ?? (/nothing/.test(r.error) ? 'empty' : /within/.test(r.error) ? 'no answer' : 'failed')}`, `doesn't work: ${r.error}${secs}`] // the reason on hover
+  return h('div', { className: 'try ' + cls },
+    h('span', { className: 'msg', textContent: text, title: about }),
+    h('button', { className: 'small', textContent: 'Test', disabled: Boolean(r?.going), title: 'send it a short message to see that it really answers', 'aria-label': `test ${t.model}`, onclick: () => tryModel(t) }))
+}
+function showTried(t) {
+  document.querySelector(`#mt li[data-key="${CSS.escape(keyOf(t))}"] .try`)?.replaceWith(triedCell(t))
+  if (SORT.some((x) => x.key === 'works') && !TRIES[keyOf(t)]?.going) drawMine(S) // sorted by it: its place may change
+}
+async function tryModel(t) {
+  TRIES[keyOf(t)] = { going: true }
+  showTried(t)
+  const r = (await act('/api/try', { provider: t.provider, model: t.model })) ?? { ok: false, error: 'the settings page did not answer' }
+  TRIES[keyOf(t)] = r
+  showTried(t)
+  return r
+}
+let testingAll = false
+async function tryAll() {
+  if (testingAll) return
+  testingAll = true
+  const list = [...(S?.order ?? [])]
+  let good = 0
+  toast(`testing ${list.length} model${list.length === 1 ? '' : 's'}…`)
+  // several at once (6), but at most 2 per provider: more would trip its rate limit and show
+  // working models as failing
+  for (const t of list) TRIES[keyOf(t)] = { going: true }
+  list.forEach(showTried)
+  const queue = [...list]
+  const busy = {}
+  const worker = async () => {
+    while (queue.length) {
+      const i = queue.findIndex((t) => (busy[t.provider] ?? 0) < 2)
+      if (i === -1) {
+        await new Promise((r) => setTimeout(r, 100)) // every waiting one's provider is busy
+        continue
+      }
+      const [t] = queue.splice(i, 1)
+      busy[t.provider] = (busy[t.provider] ?? 0) + 1
+      try {
+        if ((await tryModel(t)).ok) good++
+      } finally {
+        busy[t.provider]--
+      }
+    }
+  }
+  try {
+    await Promise.all(Array.from({ length: Math.min(6, list.length) }, worker))
+  } finally {
+    testingAll = false
+  }
+  toast(`${good} of ${list.length} work${good === list.length ? '' : `; ${list.length - good} don't (Works? says why, on hover)`}`, good < list.length)
 }
 
 // models.dev looked up again: one model (its Retry), or all of yours (Retry all)
@@ -921,16 +996,16 @@ function drawProviders(s) {
         h('button', { className: 'small', textContent: 'Retry all', title: 'look all of them up in models.dev again', style: order.length ? '' : 'visibility:hidden', onclick: () => lookUp() }),
         h('button', { className: 'small danger', textContent: 'Remove all', title: 'take every model off this list', style: order.length ? '' : 'visibility:hidden', onclick: () => confirm(`Take all ${order.length} model${order.length === 1 ? '' : 's'} off your list? HeartCode then has none to use until you choose one. (They stay under their providers.)`) && saveOrder([], 'all removed: no model chosen now') })),
       h('p', { className: 'sub', style: 'margin:0', textContent: order.length > 1 ? 'HeartCode uses #1. If it fails, it tries #2, then #3… and round again. Drag to change the order.' : order.length ? `HeartCode uses this one. Click more ${side} to add fallbacks: tried, in order, when one fails.` : `The models HeartCode uses, in the order it tries them. Click one ${side} to start.` })),
+    order.length ? h('div', { className: 'ohead' }, h('span'), h('span', { textContent: '#' }), h('span', { textContent: 'Model' }), h('span', { textContent: 'Provider' }), h('span', { textContent: 'What it can do' }), h('span')) : null,
     order.length ? h('ol', { className: 'olist' }, order.map((t, i) => h('li', {
         className: 'in', 'data-key': `${t.provider}/${t.model}`, title: order.length > 1 ? 'Drag to move it (or Alt+↑ / Alt+↓)' : '',
         onkeydown: (e) => e.altKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown') && (e.preventDefault(), move(i, Math.max(0, Math.min(order.length - 1, i + (e.key === 'ArrowUp' ? -1 : 1))))),
       },
-      order.length > 1 ? h('span', { className: 'grip', textContent: '⋮⋮', title: 'drag to reorder', 'aria-hidden': 'true' }) : null,
-      h('span', { className: 'n', textContent: `#${i + 1}` }),
-      h('div', { className: 'what' },
-        h('div', { className: 'm', textContent: t.model }),
-        h('div', { className: 'p', textContent: `${t.provider} · ${i === 0 ? 'in use' : 'fallback'}` }),
-        testLine(t)),
+      h('span', { className: 'grip', textContent: '⋮⋮', title: 'drag to reorder', 'aria-hidden': 'true', style: order.length > 1 ? '' : 'visibility:hidden' }),
+      h('span', { className: 'n', textContent: `#${i + 1}`, title: i === 0 ? 'in use: the one HeartCode uses' : 'a fallback: tried, in order, when the ones above fail' }),
+      h('span', { className: 'm', textContent: t.model, title: t.model }),
+      h('span', { className: 'p' + (i === 0 ? ' use' : ''), textContent: t.provider, title: `${t.provider}${i === 0 ? ': in use' : ''}` }),
+      testLine(t),
       h('button', { className: 'danger', textContent: '✕', title: 'take it off the list', 'aria-label': `remove ${t.model}`, onclick: () => removeMine(t.provider, t.model) })),
       ), h('li', { className: 'next', textContent: `#${order.length + 1} · click a model ${side} to add it here (a fallback)` }))
       : h('div', { className: 'mine-empty' }, h('b', { textContent: 'No model chosen yet' }), `Click a model ${side}: it becomes #1, the one HeartCode uses.`),
@@ -940,7 +1015,7 @@ function drawProviders(s) {
         h('select', { id: 'r-on', style: 'flex:1', onchange: (e) => save(order, 'saved', { on: e.target.value }) },
           [['failure', 'at its first failure'], ['retries', 'after some tries of the same model'], ['any', 'at any error']].map(([v, t]) => h('option', { value: v, textContent: t, selected: s.rotation.on === v }))),
         s.rotation.on === 'retries' ? h('input', { type: 'number', 'aria-label': 'tries', title: 'tries of the same model first', style: 'width:76px', min: 1, max: 20, value: s.rotation.retries, onchange: (e) => save(order, 'saved', { retries: Number(e.target.value) }) }) : null),
-      h('div', { className: 'hint', textContent: { failure: 'A rate limit, server error, timeout or lost connection moves on at once. Errors like "model not found" or a wrong key stop.', retries: 'The same model is tried again (with a short wait) that many times first.', any: 'Also errors like "model not found" or a bad request move on.' }[s.rotation.on] }),
+      h('div', { className: 'hint', textContent: { failure: 'A rate limit, server error, timeout or lost connection moves on at once, and so does a model it can\'t use (a wrong key, no access, "model not found"). Other errors, like a bad request, stop.', retries: 'The same model is tried again (with a short wait) that many times first.', any: 'Also errors like "model not found" or a bad request move on.' }[s.rotation.on] }),
       h('label', { className: 'f', for: 'r-next', textContent: 'A new message starts with' }),
       h('select', { id: 'r-next', onchange: (e) => save(order, 'saved', { next: e.target.value }) },
         [['first', '#1 again'], ['stay', 'the model that answered last']].map(([v, t]) => h('option', { value: v, textContent: t, selected: s.rotation.next === v })))) : null)
@@ -1122,6 +1197,7 @@ const COLS = {
   images: { label: 'Images', get: (t) => can(t).images },
   input: { label: 'In $/M', how: 'cheap', get: (t) => t.price?.input ?? null },
   output: { label: 'Out $/M', how: 'cheap', get: (t) => t.price?.output ?? null },
+  works: { label: 'Works?', get: (t) => { const r = TRIES[keyOf(t)]; return !r || r.going ? 1 : r.ok ? 2 : 0 } }, // tested and working first; not tested; not working
 }
 let SORT = (() => {
   try {
@@ -1157,7 +1233,7 @@ function sorted(order) {
   }
   return order.map((t, i) => ({ t, i })).sort((a, b) => SORT.reduce((r, s) => r || cmp(a.t, b.t, s), 0) || a.i - b.i).map((x) => x.t)
 }
-const dirText = (key, dir) => (COLS[key].how === 'text' ? (dir === 'up' ? 'A→Z' : 'Z→A') : COLS[key].how === 'cheap' ? (dir === 'up' ? 'cheapest first' : 'priciest first') : dir === 'down' ? 'most first' : 'least first')
+const dirText = (key, dir) => (key === 'works' ? (dir === 'down' ? 'working first' : 'not working first') : COLS[key].how === 'text' ? (dir === 'up' ? 'A→Z' : 'Z→A') : COLS[key].how === 'cheap' ? (dir === 'up' ? 'cheapest first' : 'priciest first') : dir === 'down' ? 'most first' : 'least first')
 function drawMine(s) {
   const order = s.order
   $('n-mine').textContent = order.length || ''
@@ -1198,10 +1274,11 @@ function drawMine(s) {
         : order.length > 1 ? 'In your order: HeartCode uses #1, then the next when one fails. Drag a row to move it, or click a column to sort.' : ''),
       SORT.length ? h('button', { className: 'small', textContent: 'Clear sort', onclick: () => setSort([]) }) : null,
       SORT.length ? h('button', { className: 'small primary', textContent: same ? 'This is your order' : 'Use this order', disabled: same, onclick: () => keep(view) }) : null,
-      order.length ? h('button', { className: 'small', textContent: 'Retry all', title: 'look all of them up in models.dev again', onclick: () => lookUp() }) : null),
+      order.length ? h('button', { className: 'small', textContent: 'Retry all', title: 'look all of them up in models.dev again', onclick: () => lookUp() }) : null,
+      order.length ? h('button', { className: 'small', textContent: 'Test all', title: 'send each a short message, several at once (2 per provider at most), to see which really answer', onclick: () => tryAll() }) : null),
     order.length
       ? h('div', { className: 'mt-scroll' }, h('div', { className: 'mt' },
-          h('div', { className: 'mt-h' }, h('span'), h('span', { textContent: '#' }), head('model'), head('provider'), head('context', true), head('abilities', true), head('tools'), head('thinking'), head('images'), head('input', true), head('output', true), h('span', { textContent: 'From' }), h('span')),
+          h('div', { className: 'mt-h' }, h('span'), h('span', { textContent: '#' }), head('model'), head('provider'), head('context', true), head('abilities', true), head('tools'), head('thinking'), head('images'), head('input', true), head('output', true), h('span', { textContent: 'From' }), head('works'), h('span')),
           h('ol', { className: 'mtable' + (order.length < 2 ? '' : ' drag') }, view.map((t) => {
             const c = can(t)
             const ctx = COLS.context.get(t)
@@ -1216,6 +1293,7 @@ function drawMine(s) {
               h('span', { className: 'num', textContent: t.price?.input != null ? usd(t.price.input) : '–' }),
               h('span', { className: 'num', textContent: t.price?.output != null ? usd(t.price.output) : '–' }),
               src(t),
+              triedCell(t),
               h('button', { className: 'danger', textContent: '✕', title: 'take it off the list', 'aria-label': `remove ${t.model}`, onclick: () => removeMine(t.provider, t.model) }))
           }))))
       : h('div', { className: 'mt-empty' }, 'No models in your list yet. ', h('a', { href: '#providers', textContent: 'Choose some under Providers & models' }), '.'))

package/src/settings.js

@@ -12,6 +12,7 @@ import { HOME, saveConfig, readJson, writeJson } from './config.js'
 import { DEFAULT_SERVERS } from './mcp.js'
 import { sections, BUILTIN_PROMPTS } from './prompts.js'
 import { Client } from './client.js'
+import { clip } from './tools.js'
 import { loadProfile, strategy, profilePath, profileFrom } from './probe.js'
 import { loadPrices, priceOf, limitsOf } from './usage.js'
 import { THEMES, PERMISSIONS } from './ui.js'
@@ -156,6 +157,17 @@ export function startSettings({ cfg, apply = () => {}, port = 0 } = {}) {
   }
 
 
+  // A failed request in a few words: its status and what the server said (its JSON's message).
+  const whyFailed = (e) => {
+    let said = String(e.body ?? '').trim()
+    try {
+      const j = [JSON.parse(said)].flat()[0]
+      said = j?.error?.message ?? (typeof j?.error === 'string' ? j.error : null) ?? (typeof j?.detail === 'string' ? j.detail : null) ?? j?.message ?? j?.title ?? said
+    } catch {}
+    if (!said || /^\s*</.test(said)) said = e.message.replace(/^\d+ from \S+: /, '')
+    return clip(`${e.status ? `${e.status}: ` : ''}${said}`, 300)
+  }
+
   const state = () => ({
     providers: Object.entries(cfg.providers)
       .filter(([n]) => n !== cfg.adhoc)
@@ -296,6 +308,22 @@ export function startSettings({ cfg, apply = () => {}, port = 0 } = {}) {
     // models.dev again (one model, or all of yours): its list fetched anew, and each model's profile
     // takes what it says now (one it didn't know before becomes "from models.dev"; your own settings
     // for it stay above). A running HeartCode takes it at once.
+    // Test: one short message to the model, to see that it answers (key, access, name, the server
+    // itself). In the requests log as a model test. Never throws: { ok, ms, reply } or { ok: false, error }.
+    'POST /api/try': async ({ provider, model } = {}) => {
+      const c = clientFor({ provider, model: String(model ?? '') })
+      if (!c || !model) return { ok: false, error: `no provider "${provider}"` }
+      c.purpose = 'test'
+      const t0 = Date.now()
+      try {
+        const r = await c.chat({ messages: [{ role: 'user', content: 'Reply with just the word OK.' }], stream: true }, { signal: AbortSignal.timeout(90_000) })
+        const reply = (r.content || '').trim()
+        if (!reply && !r.toolCalls.length) return { ok: false, ms: Date.now() - t0, error: `it answered with nothing${r.usage?.completion_tokens ? ` (${r.usage.completion_tokens} tokens it said it wrote)` : ''}` }
+        return { ok: true, ms: Date.now() - t0, reply: reply.slice(0, 80) }
+      } catch (e) {
+        return { ok: false, ms: Date.now() - t0, status: e.status ?? null, error: e.name === 'TimeoutError' ? 'no answer within 90 seconds' : whyFailed(e) }
+      }
+    },
     'POST /api/models-dev': async ({ provider, model } = {}) => {
       await loadPrices({ force: true })
       const list = provider && model ? [{ provider, model: String(model) }] : state().order.map(({ provider, model }) => ({ provider, model }))

package/src/tools.js

@@ -4,6 +4,7 @@ import { slug } from './memory.js'
 import { fillArgs } from './skills.js'
 import { prompt } from './prompts.js'
 import path from 'node:path'
+import os from 'node:os'
 import { spawn, execFileSync } from 'node:child_process'
 import { applyEdit } from './edit.js'
 import { readJson } from './config.js'
@@ -19,10 +20,27 @@ const IGNORE = new Set(['.git', 'node_modules', 'dist', 'build', '.next', 'cover
 export const clip = (s, n) => (String(s).length > n ? String(s).slice(0, n) + '…' : String(s))
 export const tail = (s, n) => (s.length > n ? '…' + s.slice(-n) : s)
 
+// Tool output too long for the conversation is saved here (one folder per chat), where read_file
+// and search can read it although it's outside the project.
+export const OUTPUTS = path.join(os.tmpdir(), 'heartcode-outputs')
+export function saveOutput(chatId, name, text) {
+  try {
+    const dir = path.join(OUTPUTS, String(chatId ?? 'chat'))
+    fs.mkdirSync(dir, { recursive: true })
+    const file = path.join(dir, `${Date.now().toString(36)}-${String(name).replace(/[^\w-]/g, '_').slice(0, 60)}.txt`)
+    fs.writeFileSync(file, text)
+    return file
+  } catch (e) {
+    log('tool', `could not save the output: ${e.message}`)
+    return ''
+  }
+}
+
 export function resolveIn(root, p) {
   const clean = String(p ?? '').trim().replace(/^["'`]+|["'`]+$/g, '')
   if (!clean) throw new Error('no path given')
   let abs = path.resolve(root, clean)
+  if (abs.startsWith(OUTPUTS + path.sep)) return abs // a saved tool output
   // "num.js:" or "num.js," from a sloppy model: the file without the stray mark, if that one exists
   const trimmed = path.resolve(root, clean.replace(/[:;,.]+$/, ''))
   if (trimmed !== abs && !fs.existsSync(abs) && fs.existsSync(trimmed)) abs = trimmed
@@ -105,13 +123,15 @@ export function searchFiles(root, query, sub = '', limit = 50) {
   } catch {
     re = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), ci ? 'i' : '')
   }
-  const prefix = sub ? path.relative(root, resolveIn(root, sub)) : ''
+  const abs = sub ? resolveIn(root, sub) : ''
+  const saved = abs.startsWith(OUTPUTS + path.sep) // a tool output saved outside the project
+  const prefix = sub && !saved ? path.relative(root, abs) : ''
   const hits = []
-  for (const f of listFiles(root)) {
+  for (const f of saved ? [abs] : listFiles(root)) {
     if (prefix && f !== prefix && !f.startsWith(prefix + '/')) continue
     let buf
     try {
-      buf = fs.readFileSync(path.join(root, f))
+      buf = fs.readFileSync(path.resolve(root, f))
     } catch {
       continue
     }
@@ -388,12 +408,51 @@ export function readOnlyCommand(cmd) {
   return c.split(/\s*(?:&&|\|\||;|\|)\s*/).every((part) => READ_ONLY.test(part))
 }
 
-// The one tool for all MCP servers, and the skill loader; each only when there's something to offer.
+// MCP servers' tools as the model sees them: each its own tool, mcp__server__tool (Claude Code's
+// names), with its description and arguments, the way the model would see them in Claude Code.
+// Servers whose tools aren't known yet (still starting, failed), or too many tools at once, go
+// through the one mcp tool instead. Sets s.mcpDirect (name → { server, tool, def }), s.mcpMeta
+// (servers behind the mcp tool) and s.mcpInstructions (what the servers say about using them).
+export const MAX_MCP_TOOLS = 100
+export async function loadMcpTools(s, signal) {
+  if (!s.mcp?.names.length) return Object.assign(s, { mcpDirect: new Map(), mcpMeta: [], mcpInstructions: '' })
+  const catalog = await s.mcp.catalog(signal)
+  // the servers with the fewest tools first, while they fit
+  const known = [...catalog].sort((a, b) => a[1].tools.length - b[1].tools.length)
+  const direct = new Map()
+  const notes = []
+  for (const [server, { tools, instructions }] of known) {
+    if (direct.size + tools.length > MAX_MCP_TOOLS) continue
+    for (const t of tools) direct.set(mcpName(server, t.name), { server, tool: t.name, def: t })
+    if (instructions) notes.push(`### ${server}\n${instructions}`)
+  }
+  const shown = new Set([...direct.values()].map((d) => d.server))
+  return Object.assign(s, { mcpDirect: direct, mcpMeta: s.mcp.names.filter((n) => !shown.has(n)), mcpInstructions: notes.join('\n\n'), mcpCatalog: catalog })
+}
+// Tool names may only have letters, digits, _ and - (64 at most).
+export const mcpName = (server, tool) => `mcp__${server}__${tool}`.replace(/[^\w-]/g, '_').slice(0, 64)
+// A schema as providers take it: an object, without the keys some refuse ($schema).
+function cleanSchema(x) {
+  if (Array.isArray(x)) return x.map(cleanSchema)
+  if (!x || typeof x !== 'object') return x
+  return Object.fromEntries(Object.entries(x).filter(([k]) => k !== '$schema').map(([k, v]) => [k, cleanSchema(v)]))
+}
+function mcpDefs(s) {
+  return [...(s.mcpDirect?.values() ?? [])].map(({ server, tool, def }) => {
+    const schema = cleanSchema(def.inputSchema ?? {})
+    return { name: mcpName(server, tool), description: clip(String(def.description ?? `${tool} (${server})`).trim(), 2000), parameters: { ...schema, type: 'object', properties: schema.properties ?? {} } }
+  })
+}
+
+// The MCP servers' tools, the one tool for the rest, and the skill loader; each only when there's
+// something to offer.
 export function extraTools(s) {
-  const out = []
-  if (s.mcp?.names.length) {
-    const servers = s.mcp.names.map((n) => `${n}: ${s.mcp.get(n).cfg.description || 'no description'}`).join('\n')
-    out.push({ name: 'mcp', description: prompt('agent/tool-mcp', { servers }), parameters: obj({ server: str, tool: str, arguments: { type: 'object' } }, ['server', 'tool']) })
+  const out = mcpDefs(s)
+  const meta = s.mcpMeta ?? s.mcp?.names ?? []
+  if (meta.length) {
+    // no description: the names of its tools, when known, say what it's for
+    const about = (n) => s.mcp.get(n).cfg.description || (s.mcpCatalog?.get(n) ? `tools: ${clip(s.mcpCatalog.get(n).tools.map((t) => t.name).join(', '), 300)}` : 'no description')
+    out.push({ name: 'mcp', description: prompt('agent/tool-mcp', { servers: meta.map((n) => `${n}: ${about(n)}`).join('\n') }), parameters: obj({ server: str, tool: str, arguments: { type: 'object' } }, ['server', 'tool']) })
   }
   if (s.memory) {
     out.push({
@@ -410,7 +469,7 @@ export function extraTools(s) {
   // the patch format OpenAI's models are trained on (they also write it as a shell command, below)
   if (/gpt|codex|\bo\d/i.test(s.client?.model ?? '')) out.push({ name: 'apply_patch', description: prompt('agent/tool-apply_patch'), parameters: obj({ input: str }, ['input']) })
   if (!s.isSub && s.subagent) out.push({ name: 'agent', description: prompt('agent/tool-agent'), parameters: obj({ description: str, prompt: str }, ['description', 'prompt']) })
-  return [...out, ...(s.director?.toolDefs(s) ?? [])] // manage (director.js)
+  return [...out, ...(s.director && !s.appendSystem ? s.director.toolDefs(s) : [])] // manage (director.js); not when a program gives the instructions (--append-system-prompt)
 }
 
 // todo: the model's checklist for this message, shown to the user each time it changes.
@@ -533,8 +592,17 @@ async function mcpTool(s, args, signal) {
     const t = tools.find((x) => x.name === a.name)
     return t ? `${t.name}: ${t.description ?? ''}\nArguments (JSON schema): ${JSON.stringify(t.inputSchema ?? {})}` : `error: ${server.name} has no tool "${a.name}"; tool "list" shows its tools`
   }
-  const ok = await s.ui.confirm(`Use ${server.name} → ${tool}?`, 'command')
-  if (ok !== true) return `The user declined this call.${typeof ok === 'string' ? ' User feedback: ' + ok : ''}`
+  return callMcp(s, server, tool, a, signal)
+}
+
+// One MCP tool call. Asked about like a command, unless the server marks the tool read-only.
+async function callMcp(s, server, tool, a, signal) {
+  if (!allowed(s, mcpName(server.name, tool))) return `error: the tool ${mcpName(server.name, tool)} is not allowed here`
+  const def = (server.tools ?? s.mcpCatalog?.get(server.name)?.tools)?.find((t) => t.name === tool)
+  if (!def?.annotations?.readOnlyHint) {
+    const ok = await s.ui.confirm(`Use ${server.name} → ${tool}?`, 'command')
+    if (ok !== true) return `The user declined this call.${typeof ok === 'string' ? ' User feedback: ' + ok : ''}`
+  }
   s.ui.spinner(`${server.name} · ${tool}`)
   const r = await server.call(tool, a, signal)
   const parts = r.content ?? []
@@ -714,8 +782,28 @@ function normalize(args) {
   return out
 }
 
+// The MCP tool a name means: mcp__server__tool (offered, or a server behind the mcp tool), or a
+// bare tool name only one server has ("click").
+function mcpTarget(s, name) {
+  const d = s.mcpDirect?.get(name)
+  if (d) return { server: s.mcp.get(d.server), tool: d.tool }
+  const m = /^mcp__(.+?)__(.+)$/.exec(name)
+  if (m && s.mcp?.get(m[1])) return { server: s.mcp.get(m[1]), tool: m[2] }
+  const same = [...(s.mcpDirect?.values() ?? [])].filter((x) => x.tool === name)
+  return same.length === 1 ? { server: s.mcp.get(same[0].server), tool: name } : null
+}
+
+// Tools the caller allowed (--allowedTools) or took away (--disallowedTools); all by default. An
+// MCP tool goes by its own name, its server's (mcp__server, as in Claude Code) or "mcp" (all of them).
+export function allowed(s, name) {
+  const names = name.startsWith('mcp__') ? [name, name.split('__').slice(0, 2).join('__'), 'mcp'] : [name]
+  if (names.some((n) => s.denyTools?.has(n))) return false
+  if (!s.allowTools) return true
+  return names.some((n) => s.allowTools.has(n)) || (name === 'mcp' && [...s.allowTools].some((n) => n.startsWith('mcp__')))
+}
+
 async function tool(name, args, s, signal) {
-  args = normalize(args)
+  if (!name.startsWith('mcp__') && !mcpTarget(s, name)) args = normalize(args) // an MCP tool's arguments are its own
   try {
     const { root } = s
     if (s.ui.permission === 'plan') {
@@ -764,8 +852,11 @@ async function tool(name, args, s, signal) {
         const k = s.skills?.get(String(args.name ?? ''))
         return k && k.use !== 'me' ? fillArgs(k.body, '') : `error: no skill "${args.name}". Skills: ${[...(s.skills?.values() ?? [])].filter((x) => x.use !== 'me').map((x) => x.name).join(', ') || 'none'}`
       }
-      default:
+      default: {
+        const m = mcpTarget(s, name)
+        if (m) return await callMcp(s, m.server, m.tool, args, signal)
         return (await s.director?.tool(name, args, s, signal)) ?? `error: there is no tool named ${name}`
+      }
     }
   } catch (e) {
     if (e.name === 'AbortError') throw e