heartcode 0.1.0 → 0.1.3

package/src/client.js

@@ -6,6 +6,9 @@ export const est = (text) => Math.ceil(String(text ?? '').length / 3.5)
 // An error that may go away by itself: a rate limit, a server error or overload, a timeout, no
 // connection (no status). Anything else (a wrong model name, key or request) won't.
 export const outage = (e) => !e.status || [408, 409, 429].includes(e.status) || e.status >= 500
+// The model can't be used as it's set up (a wrong key, no access to it, no such model): waiting
+// won't help, but the next one in the list may work.
+export const unusable = (e) => [401, 403, 404].includes(e.status)
 // A request's messages, estimated: an image's data isn't text (about 800 tokens, not its base64)
 export function estMessages(messages) {
   let images = 0
@@ -143,6 +146,16 @@ export class Client {
   get target() {
     return this.rotation?.list[this.rotation.at] ?? null
   }
+  // The model in use answers but gives nothing usable (agent.js: empty replies, again and again):
+  // the next one in the list takes over. False when there's no list.
+  moveOn(why) {
+    const r = this.rotation
+    if (!r) return false
+    r.at = (r.at + 1) % r.list.length
+    log('rotate', `${why} → ${r.list[r.at].provider} · ${r.list[r.at].model}`)
+    this.#use(r.list[r.at])
+    return true
+  }
   // A new message: back to #1 (unless it stays on the one that worked)
   newMessage() {
     const r = this.rotation
@@ -156,7 +169,7 @@ export class Client {
   #rotate(e, tries) {
     const r = this.rotation
     if (!r) return false
-    if (!(r.on === 'any' || (r.on === 'failure' && outage(e)) || (r.on === 'retries' && tries >= r.retries))) return false
+    if (!(r.on === 'any' || (r.on === 'failure' && (outage(e) || unusable(e))) || (r.on === 'retries' && (tries >= r.retries || unusable(e))))) return false
     r.at = (r.at + 1) % r.list.length
     log('rotate', `${e.message.slice(0, 200)} → ${r.list[r.at].provider} · ${r.list[r.at].model}`)
     this.#use(r.list[r.at])
@@ -186,7 +199,7 @@ export class Client {
       usage: reply?.usage,
       finishReason: reply?.finishReason,
       request: req,
-      reply: reply && { content: reply.content, reasoning: reply.reasoning, toolCalls: reply.toolCalls },
+      reply: reply && { content: reply.content, reasoning: reply.reasoning, toolCalls: reply.toolCalls, ...(reply.raw && { raw: reply.raw }) }, // raw: the stream as it came, for a reply with nothing in it
     })
   }
 
@@ -357,10 +370,11 @@ export class Client {
         if (e.name === 'AbortError' || opts.signal?.aborted) throw e
         if (tooLarge(e)) throw e // the caller shrinks the conversation and sends again
         if (this.retryIf && !this.retryIf(e, attempt)) throw e
-        // A wrong model name, key or request (404, 401, 400…): the same request fails the same way
-        // every time, so it isn't sent again. It stops here, unless the model list moves on at any
-        // error (the settings page); and a whole round of those stops too, rather than going round.
-        if (!outage(e) && this.rotation?.on !== 'any') throw e
+        // A bad request (400…): the same request fails the same way every time, so it isn't sent
+        // again. It stops here, unless the model list moves on at any error (the settings page). A
+        // model that can't be used (a wrong key or name: 401, 403, 404) makes way for the next one
+        // in the list; a whole round of those stops too, rather than going round.
+        if (!outage(e) && !(unusable(e) && this.rotation) && this.rotation?.on !== 'any') throw e
         hard &&= !outage(e)
         tries++
         if (this.#rotate(e, tries)) {
@@ -400,6 +414,14 @@ export class Client {
   // One request. Without `once`, rate limits and server errors get three quiet retries.
   async #chat(body, { onToken, onReasoning, onToolDelta, signal, once } = {}) {
     const req = { model: this.model, ...body }
+    // The model's thinking on its earlier steps (agent.js keeps it as reasoning_content): sent by the
+    // name this provider sends it by (reasoning_content: DeepSeek, vLLM…; reasoning: OpenRouter,
+    // Ollama), or not at all if it refused it once.
+    if (req.messages?.some((m) => m.reasoning_content)) {
+      const field = this.quirks.noReasoningBack ? null : (this.quirks.reasoningField ?? 'reasoning_content')
+      req.messages = req.messages.map(({ reasoning_content, ...m }) => (reasoning_content && field ? { ...m, [field]: reasoning_content } : m))
+    }
+    if (this.quirks.simpleSchemas && req.tools) req.tools = req.tools.map((t) => ({ ...t, function: { ...t.function, parameters: simpleSchema(t.function.parameters) } }))
     if (this.quirks.noTemperature) delete req.temperature
     if (this.effort && !this.quirks.noEffort) req.reasoning_effort = this.effort
     if (req.stream && !this.quirks.noStreamUsage) req.stream_options = { include_usage: true } // token counts for the status bar
@@ -423,19 +445,38 @@ export class Client {
         }
       }
     } catch (e) {
-      // Some APIs reject parameters older servers need; learn once and retry.
-      if (e.status === 400 && /temperature/.test(e.message) && 'temperature' in body && !this.quirks.noTemperature) {
+      // Some APIs reject parameters older servers need; learn once and retry. (Refused: 400, or 422
+      // from the ones that check requests against a schema, like Mistral.)
+      const refused = e.status === 400 || e.status === 422
+      const said = e.body ?? e.message
+      if (refused && /temperature/.test(e.message) && 'temperature' in body && !this.quirks.noTemperature) {
         this.quirks.noTemperature = true
         log('quirk', 'server rejects temperature')
         return this.#chat(body, { onToken, onReasoning, onToolDelta, signal, once })
       }
       for (const [quirk, param] of [['noEffort', 'reasoning_effort'], ['noStreamUsage', 'stream_options']]) {
-        if (e.status === 400 && param in req && new RegExp(param).test(e.message) && !this.quirks[quirk]) {
+        if (refused && param in req && new RegExp(param).test(e.message) && !this.quirks[quirk]) {
           this.quirks[quirk] = true
           log('quirk', `server rejects ${param}; dropping it`)
           return this.#chat(body, { onToken, onReasoning, onToolDelta, signal, once })
         }
       }
+      // The thinking sent back, or the tools' arguments (JSON schemas with keys a provider doesn't
+      // take: Gemini's "Unknown name additionalProperties"), refused: sent without it, or with
+      // simpler schemas, from now on with this model.
+      const reasoningSent = !this.quirks.noReasoningBack && body.messages?.some((m) => m.reasoning_content)
+      const noReasoning = () => {
+        this.quirks.noReasoningBack = true
+        log('quirk', 'server rejects the thinking sent back; not sending it')
+        return this.#chat(body, { onToken, onReasoning, onToolDelta, signal, once })
+      }
+      if (refused && reasoningSent && /reasoning(?!_effort)/i.test(said)) return noReasoning()
+      if (refused && body.tools?.length && !this.quirks.simpleSchemas && /schema|function_declarations|parameters|additionalProperties|exclusiveM|minItems|unknown name|invalid.{0,40}(tool|function)|tools\[/i.test(said)) {
+        this.quirks.simpleSchemas = true
+        log('quirk', 'server rejects the tools\' schemas; sending simpler ones')
+        return this.#chat(body, { onToken, onReasoning, onToolDelta, signal, once })
+      }
+      if (refused && reasoningSent && /extra|unknown|unrecognized|not permitted|additional propert/i.test(said)) return noReasoning()
       throw e
     }
     // Tokens the last request used (prompt + reply): what the status bar shows against the context size.
@@ -458,7 +499,8 @@ export class Client {
       const data = await res.json()
       const choice = data.choices?.[0] ?? {}
       const msg = choice.message ?? {}
-      return count(done(msg.content ?? '', msg.reasoning_content ?? msg.reasoning ?? '', msg.tool_calls ?? [], data.usage, choice.finish_reason))
+      this.#reasoningField(msg)
+      return count(done(textOf(msg.content), msg.reasoning_content ?? msg.reasoning ?? msg.thinking ?? '', msg.tool_calls ?? [], data.usage, choice.finish_reason))
     }
 
     const reader = res.body.getReader()
@@ -471,6 +513,7 @@ export class Client {
     let usage
     let finishReason
     const calls = []
+    let raw = '' // the stream as it came (its start), kept for a reply that turns out empty
     const emit = (v) => {
       if (onToken && v.startsWith(emitted) && v.length > emitted.length) {
         onToken(v.slice(emitted.length))
@@ -486,6 +529,7 @@ export class Client {
       while ((nl = buf.indexOf('\n')) !== -1) {
         const line = buf.slice(0, nl).trim()
         buf = buf.slice(nl + 1)
+        if (raw.length < 100_000 && line) raw += line + '\n'
         if (!line.startsWith('data:')) continue
         const payload = line.slice(5).trim()
         if (payload === '[DONE]') continue
@@ -500,8 +544,10 @@ export class Client {
         const ch = chunk.choices?.[0]
         if (!ch) continue
         if (ch.finish_reason) finishReason = ch.finish_reason
-        const d = ch.delta ?? {}
-        const r = d.reasoning_content || d.reasoning
+        const d = ch.delta ?? ch.message ?? {} // some proxies send the whole message in a chunk
+        this.#reasoningField(d)
+        if (Array.isArray(d.content)) d.content = textOf(d.content)
+        const r = d.reasoning_content || d.reasoning || d.thinking
         if (r) {
           reasoning += r
           onReasoning?.(r)
@@ -527,10 +573,48 @@ export class Client {
     }
     const result = done(content, reasoning, calls.filter(Boolean), usage, finishReason)
     emit(result.content)
+    if (!result.content.trim() && !result.toolCalls.length && !result.reasoning) {
+      result.raw = raw // nothing read from it: what came, for the requests log
+      log('reply', `${this.model}: an empty reply${usage?.completion_tokens ? ` of ${usage.completion_tokens} tokens` : ''}; the stream:`, raw.slice(0, 4000))
+    }
     return count(result)
   }
+
+  // The name this provider gives the model's thinking, to send it back by the same one.
+  #reasoningField(d) {
+    if (this.quirks.reasoningField) return
+    if (d.reasoning_content) this.quirks.reasoningField = 'reasoning_content'
+    else if (typeof d.reasoning === 'string' && d.reasoning) this.quirks.reasoningField = 'reasoning'
+  }
 }
 
+// A tool's arguments as the most limited providers take them (Gemini's function declarations):
+// only types, properties, required, items, enum and descriptions; a choice of types (anyOf, oneOf,
+// ["string", "null"]) becomes its first real one.
+const KEEP = new Set(['type', 'properties', 'required', 'items', 'enum', 'description'])
+export function simpleSchema(x) {
+  if (!x || typeof x !== 'object' || Array.isArray(x)) return x
+  const alt = x.anyOf ?? x.oneOf
+  if (alt?.length) {
+    const pick = alt.find((a) => a?.type !== 'null') ?? alt[0]
+    return simpleSchema({ ...pick, ...(x.description && { description: x.description }) })
+  }
+  const out = {}
+  for (const [k, v] of Object.entries(x)) {
+    if (!KEEP.has(k)) continue
+    if (k === 'properties') out.properties = Object.fromEntries(Object.entries(v ?? {}).map(([n, s]) => [n, simpleSchema(s)]))
+    else if (k === 'items') out.items = simpleSchema(Array.isArray(v) ? v[0] : v)
+    else if (k === 'type' && Array.isArray(v)) out.type = v.find((y) => y !== 'null') ?? 'string'
+    else out[k] = v
+  }
+  out.type ??= out.properties ? 'object' : 'string'
+  if (Array.isArray(out.required) && out.properties) out.required = out.required.filter((r) => r in out.properties)
+  return out
+}
+
+// Message content as text: a string, or a list of parts ({ type: 'text', text }).
+const textOf = (c) => (Array.isArray(c) ? c.map((p) => (typeof p === 'string' ? p : (p?.text ?? ''))).join('') : (c ?? ''))
+
 function done(raw, reasoning, toolCalls, usage, finishReason) {
   const calls = toolCalls.filter((c) => c?.function?.name)
   calls.forEach((c, i) => (c.id ||= `call_${Date.now()}_${i}`))

package/src/config.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 export const HOME = process.env.HEART_HOME || path.join(os.homedir(), '.heart')
 export const CONFIG_FILE = path.join(HOME, 'config.json')
@@ -16,6 +17,9 @@ export function readJson(file, fallback) {
   }
 }
 
+// HeartCode's version, from package.json (npm version changes it there).
+export const VERSION = readJson(fileURLToPath(new URL('../package.json', import.meta.url)), {}).version ?? '0.0.0'
+
 // A config file the user writes (hooks.json, mcp.json): one that doesn't parse is skipped, but
 // said (takeConfigErrors, shown before the next message), never silently ignored.
 const configErrors = new Map() // file → { message, stamp, shown }

package/src/guided.js

@@ -44,6 +44,7 @@ export function newFileIn(task, files) {
 // Obvious next steps are taken without asking: a weak model's effort goes into
 // writing code, not into navigating. Returns an action, or null to ask.
 export function autoAction(st) {
+  if (st.delegated) return 'finish' // another model did the task: say what it did
   if (st.newFile && st.wantsChange) return 'create'
   if (st.failing && st.canRun && !st.runs && !st.edits) return 'run' // see the failure first
   if (st.lastRun !== null && st.lastRun !== 0 && !st.editsSinceRun && st.wantsChange && st.fixes < 3) return 'edit'
@@ -61,7 +62,7 @@ export function nextActions(st) {
   if (!st.reads && st.hasFiles) first = ['read', 'search']
   else if (st.wantsChange && !st.edits) first = st.hasFiles ? ['edit', 'create', 'read'] : ['create']
   else first = ['finish', 'edit', 'run']
-  return [...new Set([...first, ...ACTIONS.map(([n]) => n)])]
+  return [...new Set([...first, ...ACTIONS.map(([n]) => n)])].filter((n) => n !== 'delegate' || st.canDelegate)
 }
 
 // A reply may be plain text or (when enforced) JSON like {"path": "a.js"}.
@@ -193,7 +194,7 @@ class Guided {
     this.notes = []
     this.changed = new Set()
     this.files = listFiles(s.root)
-    this.st = { reads: 0, edits: 0, editsSinceRun: 0, runs: 0, fixes: 0, lastRun: null, hasFiles: this.files.length > 0, canRun: suggestCommands(s.root).length > 0 }
+    this.st = { reads: 0, edits: 0, editsSinceRun: 0, runs: 0, fixes: 0, lastRun: null, hasFiles: this.files.length > 0, canRun: suggestCommands(s.root).length > 0, canDelegate: Boolean(s.team?.().some((t) => t.tools)) }
   }
 
   async yesNo(question, fallback) {
@@ -585,6 +586,16 @@ class Guided {
     return `ask:${q}`
   }
 
+  // Another of your models, one with tool calls, does the whole task; what it did goes in the notes.
+  async delegate() {
+    const team = this.s.team().filter((t) => t.tools)
+    const t = (/\.(png|jpe?g|gif|webp)\b/i.test(this.task) && team.find((x) => x.images)) || team[0]
+    const done = await this.s.subagent({ description: 'the task', prompt: this.task, model: `${t.provider} ${t.model}` }, this.signal)
+    this.note('delegate', `what ${t.model} did for the task`, done)
+    this.st.delegated = true
+    return 'delegate'
+  }
+
   async finish() {
     this.ui.spinner('writing answer')
     let res

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.
@@ -93,15 +93,29 @@ export async function runHeadless(app, opts) {
   const model = `${app.cfg.provider}/${s.client.model}`
 
   // usage and request count, over everything this message sends (tool loop, compaction, memory)
+  // (also your other models', when this one hands them a job: modelUsage has each)
   let usage = { input_tokens: 0, output_tokens: 0 }
+  let byModel = {}
   let requests = 0
-  const chat = s.client.chat.bind(s.client)
-  s.client.chat = async (...a) => {
-    const r = await chat(...a)
-    requests++
-    usage.input_tokens += r.usage?.prompt_tokens ?? 0
-    usage.output_tokens += r.usage?.completion_tokens ?? 0
-    return r
+  const count = (client, key) => {
+    const chat = client.chat.bind(client)
+    client.chat = async (...a) => {
+      const r = await chat(...a)
+      const m = (byModel[key] ??= { inputTokens: 0, outputTokens: 0 })
+      if (client === s.client) requests++
+      usage.input_tokens += r.usage?.prompt_tokens ?? 0
+      usage.output_tokens += r.usage?.completion_tokens ?? 0
+      m.inputTokens += r.usage?.prompt_tokens ?? 0
+      m.outputTokens += r.usage?.completion_tokens ?? 0
+      return r
+    }
+  }
+  count(s.client, model)
+  const engineFor = s.engineFor
+  if (engineFor) s.engineFor = async (t) => {
+    const e = await engineFor(t)
+    count(e.client, `${t.provider}/${t.model}`)
+    return e
   }
 
   let said = false // the model's text was already sent as an assistant message
@@ -119,8 +133,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 }
@@ -128,6 +143,7 @@ export async function runHeadless(app, opts) {
     const t0 = Date.now()
     const spent = app.chat.usage?.cost ?? 0
     usage = { input_tokens: 0, output_tokens: 0 }
+    byModel = {}
     requests = 0
     said = false
     current = { ctl: new AbortController() }
@@ -147,7 +163,7 @@ export async function runHeadless(app, opts) {
     }
     const subtype = current.maxTurns ? 'error_max_turns' : error ? 'error_during_execution' : 'success' // as Claude Code names them
     current = null
-    const result = { type: 'result', subtype, is_error: Boolean(error), result: error ?? answer, num_turns: Math.max(1, requests), duration_ms: Date.now() - t0, total_cost_usd: (app.chat.usage?.cost ?? 0) - spent, usage, modelUsage: { [model]: { inputTokens: usage.input_tokens, outputTokens: usage.output_tokens } }, session_id }
+    const result = { type: 'result', subtype, is_error: Boolean(error), result: error ?? answer, num_turns: Math.max(1, requests), duration_ms: Date.now() - t0, total_cost_usd: (app.chat.usage?.cost ?? 0) - spent, usage, modelUsage: { [model]: { inputTokens: 0, outputTokens: 0 }, ...byModel }, session_id }
     if (out === 'stream-json') {
       if (!error && answer && !said) emit({ type: 'assistant', message: { role: 'assistant', model, content: [{ type: 'text', text: answer }] }, session_id }) // guided mode
       emit(result)

package/src/log.js

@@ -28,14 +28,23 @@ export function stamp(d = new Date()) {
 }
 // Logs older than `days` go: run folders, request folders, and the older one-file-per-run logs.
 // Returns how many went.
-export function pruneLogs(days = DAYS) {
-  const before = Date.now() - days * 86_400_000
+// When a log was last written to: a folder's newest file (writing into a file leaves its folder's
+// time as it was).
+function lastWritten(at) {
+  const s = fs.statSync(at)
+  if (!s.isDirectory()) return s.mtimeMs
+  let t = s.mtimeMs
+  for (const f of fs.readdirSync(at)) t = Math.max(t, fs.statSync(path.join(at, f), { throwIfNoEntry: false })?.mtimeMs ?? 0)
+  return t
+}
+
+export function pruneLogs(days = DAYS, before = Date.now() - days * 86_400_000) {
   let gone = 0
   for (const [dir, isLog] of [[path.join(LOGS, 'runs'), () => true], [REQUESTS, () => true], [LOGS, (f) => f.endsWith('.log')]]) {
     try {
       for (const f of fs.readdirSync(dir)) {
         const at = path.join(dir, f)
-        if (!isLog(f) || at === LOG_DIR || at === requestLog.dir || fs.statSync(at).mtimeMs >= before) continue
+        if (!isLog(f) || at === LOG_DIR || at === requestLog.dir || lastWritten(at) >= before) continue
         fs.rmSync(at, { recursive: true, force: true })
         gone++
       }
@@ -43,6 +52,31 @@ export function pruneLogs(days = DAYS) {
   }
   return gone
 }
+// The settings page's Delete all: every log but the ones being written now (this run's, and any
+// touched in the last minute: another HeartCode's). Returns how many files and folders went.
+export const clearLogs = () => pruneLogs(0, Date.now() - 60_000)
+
+// How much room the logs take on disk, in bytes: { runs, requests, total } (runs: the run logs,
+// and older single log files).
+export function logSize() {
+  const sum = (dir) => {
+    let n = 0
+    try {
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const at = path.join(dir, e.name)
+        n += e.isDirectory() ? sum(at) : (fs.statSync(at, { throwIfNoEntry: false })?.size ?? 0)
+      }
+    } catch {}
+    return n
+  }
+  let loose = 0
+  try {
+    for (const f of fs.readdirSync(LOGS)) if (f.endsWith('.log')) loose += fs.statSync(path.join(LOGS, f), { throwIfNoEntry: false })?.size ?? 0
+  } catch {}
+  const runs = sum(path.join(LOGS, 'runs')) + loose
+  const requests = sum(REQUESTS)
+  return { runs, requests, total: runs + requests }
+}
 export const logDays = (cfg) => (Number.isInteger(cfg.logDays) && cfg.logDays > 0 ? cfg.logDays : DAYS)
 
 // Which tab this is running for (tabs.js runs each tab's work in it): its log file, its requests.

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()