heartcode 0.0.0-stage → 0.1.1

package/prompts/guided.md

@@ -0,0 +1,193 @@
+# guided.md
+
+What weak models see in guided mode: one question at a time.
+Each `## name` below is one prompt. `{{placeholders}}` are filled in by HeartCode;
+a `<!-- … -->` note under a heading explains the prompt and is never sent. To change one, copy
+its section into ~/.heart/prompts/guided.md (every project) or .heartcode/prompts/guided.md (one project).
+
+## system
+
+<!-- System prompt in guided mode (weak models: one question at a time). -->
+You are HeartCode, a careful coding assistant working inside the user's project.
+You work in small steps. Each message asks you ONE question. Answer exactly that question, in the requested form, and nothing else.
+
+## context
+
+<!-- What comes before every guided question.
+{{task}}: the user's message. {{history}}: earlier messages and answers (may be empty).
+{{files}}: the project's files (or a note that there are none). {{done}}: notes on the steps so far (may be empty). -->
+TASK: {{task}}
+{{#if history}}
+EARLIER IN THIS CONVERSATION:
+{{history}}
+{{/if}}
+PROJECT FILES:{{files}}
+{{#if done}}
+WHAT HAS BEEN DONE SO FAR:
+{{done}}{{/if}}
+
+## actions
+
+<!-- The steps guided mode can take, one per line as "name: what it does".
+The names are fixed (HeartCode acts on them); the descriptions are what the model sees in the menu. -->
+read: look at a file
+search: find text in the project files
+edit: change an existing file
+create: make a new file
+run: run a shell command (tests, build, scripts)
+ask: ask the user a question
+finish: stop and give your final answer to the user
+
+## next-action
+
+<!-- The step menu. {{menu}}: numbered steps, likeliest first. -->
+What should you do next for the TASK?
+{{menu}}
+
+Read a file before editing it. If the task is done, or it was only a question you can now answer, choose finish.
+Reply with only the number.
+
+## next-action-retry
+
+<!-- Added to the step menu when the reply wasn't a number. {{reply}}: what it said. {{count}}: how many steps. -->
+Your reply "{{reply}}" is not a number from 1 to {{count}}. Reply with only the number.
+
+## yes-no
+
+<!-- A yes/no question. {{question}}: the question. -->
+{{question}}
+Reply with only yes or no.
+
+## intent
+
+<!-- Asked only when the wording of the task doesn't say whether it needs changes. -->
+Does the TASK require changing existing code or creating files (not just answering a question)?
+
+## pick-file
+
+<!-- Choosing a file. {{question}}: e.g. which-file-to-read. -->
+{{question}}
+Reply with only the file path.
+
+## pick-file-retry
+
+<!-- The answer wasn't a project file. {{said}}: the answer. {{choices}}: the closest files, one per line. -->
+{{question}}
+Your answer "{{said}}" is not a file in the project. Choose one of these:
+{{choices}}
+Reply with only the file path.
+
+## which-file-to-read
+
+Which file do you want to read?
+
+## which-file-to-edit
+
+Which existing file should be changed?
+
+## search
+
+What text should be searched for in the project files? Reply with only the search text.
+
+## edit-blocks
+
+<!-- Editing with SEARCH/REPLACE blocks. {{file}}: path. {{content}}: the file, fenced. -->
+Here is the current content of {{file}}:
+{{content}}
+
+Write one or more SEARCH/REPLACE blocks that make the change needed for the TASK. Use exactly this format:
+<<<<<<< SEARCH
+(lines copied exactly from the file)
+=======
+(the new lines)
+>>>>>>> REPLACE
+Reply with only the blocks.
+
+## rewrite
+
+<!-- Rewriting a whole file. {{file}}: path. {{content}}: the file, fenced. {{extra}}: an extra instruction (may be empty). -->
+Here is the current content of {{file}}:
+{{content}}
+
+Rewrite this file with the change needed for the TASK. Reply with the COMPLETE new file content and nothing else. Keep everything that should not change. Never use placeholders like "rest of code here".{{#if extra}}
+{{extra}}{{/if}}
+
+## keep-names
+
+<!-- An edit deleted definitions the task didn't ask to remove. {{names}}: them. {{them}}: "it" or "them". -->
+Your previous attempt deleted {{names}}. The TASK does not ask for that, so keep {{them}} exactly as is.
+
+## find-place
+
+<!-- The file is too long to show. {{file}}: path. -->
+{{file}} is too long to show whole. What word or text in it marks the place that needs to change for the TASK? Reply with only that text.
+
+## pick-range
+
+<!-- Choosing the lines to rewrite in a long file. {{file}}: path. {{part}}: " (lines 10-80 of 400)" or empty. {{view}}: numbered lines, fenced. -->
+Here is part of {{file}}{{part}}, with line numbers:
+{{view}}
+
+Which lines need to change for the TASK? Reply with only the line range, like 12-30.
+
+## rewrite-range
+
+<!-- Rewriting a line range. {{file}}, {{a}}-{{b}}: the range. {{chunk}}, {{before}}, {{after}}: fenced code. {{extra}}: an extra instruction (may be empty). -->
+In {{file}}, these are lines {{a}}-{{b}}:
+{{chunk}}
+
+The lines just before them:
+{{before}}
+The lines just after them:
+{{after}}
+
+Write the new code that replaces lines {{a}}-{{b}} for the TASK (it can be more or fewer lines).{{#if extra}}
+{{extra}}{{/if}} Reply with only that code.
+
+## new-file-path
+
+What is the path of the new file, relative to the project root? Reply with only the path.
+
+## new-file
+
+<!-- {{file}}: the new file's path. -->
+Write the full content of the new file {{file}} for the TASK. Reply with only the file content.
+
+## run
+
+<!-- Choosing a command. {{commands}}: the project's known commands, numbered (may be empty). -->
+Which shell command should be run?
+{{#if commands}}Commands this project has:
+{{commands}}
+
+Reply with a number from the list, or with a different shell command.{{else}}Reply with only the shell command.{{/if}}
+
+## ask-user
+
+What question do you want to ask the user? Reply with only the question.
+
+## finish
+
+Now write your final reply to the user: answer their request, or briefly summarize what was changed. Be clear and concise.
+
+## describe-image
+
+<!-- For an image attached with @file.png. {{task}}: the user's message. -->
+The user attached this image to the task: "{{task}}". Describe everything in it that matters for the task: text, code, error messages, layout. Be thorough but concise.
+
+## note-repeated
+
+You just did the same thing twice. Choose something different, or finish if the task is done.
+
+## note-no-files
+
+There are no files in the project.
+
+## note-unknown-file
+
+Could not work out which file was meant.
+
+## note-tests-are-right
+
+<!-- A weak model tried to edit a failing test instead of the code it tests. {{test}}, {{code}}: the files. -->
+The tests in {{test}} are correct; fix {{code}}, the code they test.

package/prompts/probe.md

@@ -0,0 +1,67 @@
+# probe.md
+
+The one-time test of a new model's abilities. Changing these changes how models are judged.
+Each `## name` below is one prompt. `{{placeholders}}` are filled in by HeartCode;
+a `<!-- … -->` note under a heading explains the prompt and is never sent. To change one, copy
+its section into ~/.heart/prompts/probe.md (every project) or .heartcode/prompts/probe.md (one project).
+
+## capital
+
+What is the capital of France? Answer in one word.
+
+## count
+
+Count from 1 to 10, separated by spaces. Reply with only the numbers.
+
+## edit
+
+<!-- The "edit skill" test. {{code}}: a small file. {{ask}}: the change to make. -->
+Here is a file:
+```
+{{code}}```
+
+{{ask}}
+Reply with only a SEARCH/REPLACE block in exactly this format:
+<<<<<<< SEARCH
+(exact lines to find)
+=======
+(replacement lines)
+>>>>>>> REPLACE
+
+## exact-number
+
+<!-- The "exact format" test. {{n}}: a number. -->
+Reply with only the number {{n}}. No other words.
+
+## hello
+
+Say hello in one short sentence.
+
+## image-color
+
+What color is this image? Reply with one word.
+
+## menu
+
+<!-- The "menu picking" test. {{what}}: e.g. "a fruit". {{list}}: numbered options. -->
+Which of these is {{what}}?
+{{list}}
+Reply with only the number.
+
+## system
+
+<!-- The system prompt of the "follows the system prompt" test; the model passes by replying BANANA. -->
+Whatever the user says, reply with only the single word BANANA.
+
+## tool-description
+
+Look up the secret code for a name.
+
+## tool-question
+
+<!-- The tool-call test. {{name}}: the name to look up. -->
+What is the secret code for "{{name}}"? Use the get_secret_code tool to find out.
+
+## tool-result
+
+The secret code is ZX-4417.

package/src/acp.js

@@ -0,0 +1,248 @@
+// heartcode --acp: the Agent Client Protocol (https://agentclientprotocol.com), for editors that
+// run coding agents (Zed, JetBrains, Neovim's CodeCompanion, …). JSON-RPC 2.0 over stdin/stdout,
+// one message per line. The editor starts sessions (session/new, session/load) and sends prompts
+// (session/prompt); HeartCode streams its answer, thinking, tool calls and todo list back
+// (session/update) and asks the editor before edits and commands (session/request_permission), as
+// the permission mode says (the editor's mode picker: session/set_mode).
+// In Zed's settings.json: "agent_servers": { "HeartCode": { "command": "heartcode", "args": ["--acp"] } }
+import readline from 'node:readline'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { log } from './log.js'
+import { clip } from './tools.js'
+import { HeadlessUI } from './headless.js'
+import { PERMISSIONS } from './ui.js'
+import { loadChat } from './sessions.js'
+
+const KIND = { read_file: 'read', list_files: 'search', search: 'search', edit_file: 'edit', write_file: 'edit', run_command: 'execute', web_fetch: 'fetch', web_search: 'fetch', todo: 'think', agent: 'think' }
+const plain = (s) => String(s ?? '').replace(/\x1b\[[0-9;]*m/g, '')
+
+// The screen for one session: everything goes to the editor as session/update.
+class AcpUI extends HeadlessUI {
+  constructor(conn, permission) {
+    super({ permission })
+    Object.assign(this, { conn, sessionId: null, calls: [] })
+  }
+  update(u) {
+    this.conn.notify('session/update', { sessionId: this.sessionId, update: u })
+  }
+  response() {
+    const chunk = (sessionUpdate) => (text) => text && this.update({ sessionUpdate, content: { type: 'text', text } })
+    return { text: chunk('agent_message_chunk'), think: chunk('agent_thought_chunk'), end() {} }
+  }
+  setPermission(mode) {
+    super.setPermission(mode)
+    if (this.sessionId) this.update({ sessionUpdate: 'current_mode_update', currentModeId: mode })
+  }
+  async confirm(question, kind = 'edit') {
+    if ((this.permission === 'all' || (this.permission === 'commands' && kind === 'edit') || (this.permission === 'plan' && kind === 'read'))) return true
+    const toolCallId = this.calls[0] ?? `ask_${Date.now()}`
+    const r = await this.conn
+      .request('session/request_permission', {
+        sessionId: this.sessionId,
+        toolCall: { toolCallId, title: plain(question) },
+        options: [
+          { optionId: 'allow', name: 'Allow', kind: 'allow_once' },
+          { optionId: 'all', name: 'Allow everything from now on', kind: 'allow_always' },
+          { optionId: 'reject', name: 'Reject', kind: 'reject_once' },
+        ],
+      })
+      .catch(() => null)
+    const id = r?.outcome?.outcome === 'selected' ? r.outcome.optionId : null
+    if (id === 'all') this.setPermission('all')
+    return id === 'allow' || id === 'all'
+  }
+}
+
+// JSON-RPC over stdio.
+function connection(input, output) {
+  let next = 1
+  const pending = new Map()
+  const send = (msg) => output.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n')
+  return {
+    send,
+    pending,
+    notify: (method, params) => send({ method, params }),
+    request: (method, params) =>
+      new Promise((resolve, reject) => {
+        const id = `hc${next++}`
+        pending.set(id, { resolve, reject })
+        send({ id, method, params })
+      }),
+  }
+}
+
+// makeApp(root, ui, mcpServers) → an App (bin/heartcode.js) for a session's folder.
+export async function runAcp({ makeApp, version, permission = 'ask', input = process.stdin, output = process.stdout }) {
+  const conn = connection(input, output)
+  const sessions = new Map() // id → { app, ui, ctl }
+  const modes = (current) => ({ currentModeId: current, availableModes: PERMISSIONS.map(([id, description]) => ({ id, name: id, description })) })
+
+  const open = async (cwd, mcpServers, chat) => {
+    const ui = new AcpUI(conn, permission)
+    const app = makeApp(path.resolve(cwd || process.cwd()), ui, toMcp(mcpServers))
+    if (chat) app.setChat(chat)
+    ui.sessionId = app.chat.id
+    const s = await app.session()
+    if (!s) throw Object.assign(new Error('no model set up: run heart settings to add a provider and choose a model'), { code: -32000 })
+    s.onEvent = (e) => events(ui, s, e)
+    sessions.set(ui.sessionId, { app, ui, ctl: null })
+    return { app, ui }
+  }
+
+  const methods = {
+    initialize: () => ({
+      protocolVersion: 1,
+      agentCapabilities: { loadSession: true, promptCapabilities: { image: true, audio: false, embeddedContext: true }, mcpCapabilities: { http: true, sse: true } },
+      authMethods: [],
+      agentInfo: { name: 'heartcode', title: 'HeartCode', version },
+    }),
+    'session/new': async ({ cwd, mcpServers }) => {
+      const { ui } = await open(cwd, mcpServers)
+      return { sessionId: ui.sessionId, modes: modes(ui.permission) }
+    },
+    'session/load': async ({ sessionId, cwd, mcpServers }) => {
+      const chat = loadChat(sessionId)
+      if (!chat) throw Object.assign(new Error(`no session ${sessionId}`), { code: -32002 })
+      const { ui } = await open(cwd ?? chat.root, mcpServers, chat)
+      for (const h of chat.history) {
+        ui.update({ sessionUpdate: 'user_message_chunk', content: { type: 'text', text: h.task } })
+        ui.update({ sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: h.answer } })
+      }
+      return { modes: modes(ui.permission) }
+    },
+    'session/set_mode': ({ sessionId, modeId }) => {
+      const it = sessions.get(sessionId)
+      if (!it) throw Object.assign(new Error(`no session ${sessionId}`), { code: -32002 })
+      if (!PERMISSIONS.some(([p]) => p === modeId)) throw Object.assign(new Error(`no mode ${modeId}`), { code: -32602 })
+      it.ui.setPermission(modeId)
+      return {}
+    },
+    'session/cancel': ({ sessionId }) => sessions.get(sessionId)?.ctl?.abort(),
+    'session/prompt': async ({ sessionId, prompt }) => {
+      const it = sessions.get(sessionId)
+      if (!it) throw Object.assign(new Error(`no session ${sessionId}`), { code: -32002 })
+      const { app } = it
+      const { text, images } = promptOf(prompt, app.root)
+      it.ctl = new AbortController()
+      app.signal = it.ctl.signal
+      try {
+        const k = /^\/(\S+)\s*([\s\S]*)$/.exec(text)
+        const skill = k && app.skills.get(k[1])
+        await app.s.run(skill && skill.use !== 'model' ? await app.expandSkill(skill, k[2]) : text, it.ctl.signal, images)
+        return { stopReason: 'end_turn' }
+      } catch (e) {
+        if (it.ctl.signal.aborted) return { stopReason: 'cancelled' }
+        if (e.maxTurns) return { stopReason: 'max_turn_requests' }
+        throw e
+      } finally {
+        it.ctl = null
+        it.ui.calls = []
+        app.save()
+      }
+    },
+  }
+
+  const rl = readline.createInterface({ input, crlfDelay: Infinity })
+  const running = new Set()
+  for await (const line of rl) {
+    if (!line.trim()) continue
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      conn.send({ id: null, error: { code: -32700, message: 'parse error' } })
+      continue
+    }
+    if (msg.method === undefined && msg.id !== undefined) {
+      // an answer to one of HeartCode's requests
+      const p = conn.pending.get(msg.id)
+      conn.pending.delete(msg.id)
+      msg.error ? p?.reject(new Error(msg.error.message)) : p?.resolve(msg.result)
+      continue
+    }
+    const fn = methods[msg.method]
+    log('acp', `← ${msg.method}`, clip(JSON.stringify(msg.params ?? {}), 2000))
+    const job = (async () => {
+      if (!fn) {
+        if (msg.id !== undefined) conn.send({ id: msg.id, error: { code: -32601, message: `HeartCode does not support ${msg.method}` } })
+        return
+      }
+      try {
+        const result = await fn(msg.params ?? {})
+        if (msg.id !== undefined) conn.send({ id: msg.id, result: result ?? null })
+      } catch (e) {
+        log('acp', `${msg.method} failed: ${e.stack}`)
+        if (msg.id !== undefined) conn.send({ id: msg.id, error: { code: e.code ?? -32603, message: e.message } })
+      }
+    })()
+    running.add(job)
+    job.finally(() => running.delete(job))
+  }
+  await Promise.all(running)
+  return 0
+}
+
+// Tool calls and results → the editor's tool call list; the todo list → its plan.
+function events(ui, s, e) {
+  if (e.type === 'assistant') {
+    for (const t of e.toolCalls) {
+      let args = {}
+      try {
+        args = JSON.parse(t.function.arguments || '{}')
+      } catch {}
+      const name = t.function.name
+      const what = args.command ?? args.path ?? args.url ?? args.query ?? args.description ?? (args.server ? `${args.server} · ${args.tool}` : '')
+      ui.calls.push(t.id)
+      ui.update({
+        sessionUpdate: 'tool_call',
+        toolCallId: t.id,
+        title: clip(`${name}${what ? ` ${what}` : ''}`, 120),
+        kind: KIND[name] ?? 'other',
+        status: 'pending',
+        rawInput: args,
+        ...(args.path && { locations: [{ path: path.resolve(s.root, String(args.path)) }] }),
+      })
+    }
+  } else if (e.type === 'tool') {
+    ui.calls = ui.calls.filter((id) => id !== e.id)
+    const failed = /^error/.test(e.output)
+    ui.update({ sessionUpdate: 'tool_call_update', toolCallId: e.id, status: failed ? 'failed' : 'completed', content: [{ type: 'content', content: { type: 'text', text: clip(plain(e.output), 4000) } }] })
+    if (e.name === 'todo') ui.update({ sessionUpdate: 'plan', entries: (s.chat.todos ?? []).map((t) => ({ content: t.content, priority: 'medium', status: t.status })) })
+  }
+}
+
+// The prompt's content blocks: text, images, files (linked or with their text).
+export function promptOf(blocks, root) {
+  const text = []
+  const images = []
+  for (const b of [blocks].flat()) {
+    if (!b) continue
+    if (b.type === 'text') text.push(b.text)
+    else if (b.type === 'image' && b.data) images.push(`data:${b.mimeType ?? 'image/png'};base64,${b.data}`)
+    else if (b.type === 'resource_link') text.push(rel(b.uri, root))
+    else if (b.type === 'resource' && b.resource) {
+      const r = b.resource
+      text.push(r.text !== undefined ? `${rel(r.uri, root)}:\n\`\`\`\n${r.text}\n\`\`\`` : rel(r.uri, root))
+    }
+  }
+  return { text: text.join('\n\n'), images }
+}
+
+const rel = (uri, root) => {
+  try {
+    return uri?.startsWith('file:') ? path.relative(root, fileURLToPath(uri)) || '.' : String(uri)
+  } catch {
+    return String(uri)
+  }
+}
+
+// The editor's MCP servers → HeartCode's config ({ name, command, args, env: [{name, value}] } or { type: http|sse, url, headers }).
+function toMcp(list = []) {
+  const kv = (xs) => Object.fromEntries((xs ?? []).map((x) => [x.name, x.value]))
+  const servers = Object.fromEntries(
+    list.map((m) => [m.name, m.command ? { command: m.command, args: m.args ?? [], env: kv(m.env) } : { url: m.url, type: m.type === 'sse' ? 'sse' : 'http', headers: kv(m.headers) }]),
+  )
+  return list.length ? JSON.stringify({ mcpServers: servers }) : null
+}
+