@hncode/hncode 0.6.0 → 0.6.2

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "@hncode/hncode",
-  "version": "0.6.0",
-  "description": "hncode — A cyan-blue TUI AI coding agent with zero runtime dependencies.",
-  "type": "module",
-  "main": "src/index.js",
-  "bin": {
-    "hncode": "bin/hncode"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "LICENSE",
-    "README.md",
-    "README_CN.md",
-    "package.json"
-  ],
-  "scripts": {
-    "preinstall": "node bin/preinstall.cjs",
-    "install": "node bin/install.cjs",
-    "i18n": "node tools/sync-i18n.mjs",
-    "i18n:check": "node tools/sync-i18n.mjs --check",
-    "test": "node --test \"test/**/*.test.mjs\""
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "license": "PolyForm-Noncommercial-1.0.0",
-  "author": "NiceHello666",
-  "keywords": [
-    "cli",
-    "agent",
-    "coding",
-    "ai",
-    "tui"
-  ]
-}
+{
+  "name": "@hncode/hncode",
+  "version": "0.6.2",
+  "description": "hncode — A cyan-blue TUI AI coding agent with zero runtime dependencies.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "hncode": "bin/hncode"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md",
+    "README_CN.md",
+    "package.json"
+  ],
+  "scripts": {
+    "preinstall": "node bin/preinstall.cjs",
+    "install": "node bin/install.cjs",
+    "i18n": "node tools/sync-i18n.mjs",
+    "i18n:check": "node tools/sync-i18n.mjs --check",
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "author": "NiceHello666",
+  "keywords": [
+    "cli",
+    "agent",
+    "coding",
+    "ai",
+    "tui"
+  ]
+}

package/src/clipboard.js

@@ -62,33 +62,51 @@ function win() { return process.platform === 'win32'; }
 /**
  * Put text on the clipboard.
  *
- * WINDOWS: `Set-Clipboard` through PowerShell, NOT `clip.exe`.
+ * WINDOWS: `clip.exe` on STDIN, with the PowerShell path as the fallback.
  *
- * `clip.exe` takes UTF-16LE and needed a byte order mark to be read correctly — without it
- * non-ASCII arrived as mojibake (`中文测试` came back as `-N噀Km諎`, measured). But the mark is then
- * part of the clipboard text: every copy began with a zero-width U+FEFF that showed up as a stray
- * invisible character wherever it was pasted. Measured over six samples, `Set-Clipboard` was better
- * on every one:
+ * An earlier version chose `Set-Clipboard` because `clip.exe` prefixed every copy with a zero-width U+FEFF.
+ * That was a BOM problem, not a `clip.exe` problem: it reads stdin as a byte stream, so a leading `FF FE` is
+ * two literal characters. Sent as plain UTF-16LE with no mark, it round-trips exactly — verified on ASCII,
+ * Chinese, emoji, embedded newlines and 400000 characters.
  *
- *     copied           clip.exe + BOM             Set-Clipboard
- *     hello            U+FEFF hello               hello
- *     中文测试          U+FEFF 中文测试             中文测试
- *     line1\nline2     U+FEFF line1 CRLF line2    line1\nline2   (line endings untouched)
- *     emoji 🎉 ok       U+FEFF emoji 🎉 ok         emoji 🎉 ok
+ * Two measured reasons to prefer it:
  *
- * It also needs no escaping: PowerShell receives a .NET string rather than a byte stream, so there
- * is no console parser to satisfy — which is what the BOM and the quoting were working around.
+ *   characters   clip.exe   pwsh one-shot
+ *          100      77ms          788ms
+ *         5000      56ms          748ms
+ *        20000      61ms   ENAMETOOLONG   <- the command line is capped near 32KB
+ *       400000      58ms   ENAMETOOLONG
  *
- * `clip.exe` stays as a fallback for a machine with no PowerShell at all, where a copy carrying a
- * stray BOM beats no copy.
+ * `clip.exe` takes the text on STDIN, so its cost does not depend on the length and it has no ceiling; the
+ * PowerShell route puts the text on its COMMAND LINE and fails outright past ~20k characters. The one
+ * difference that remains: `clip.exe` normalises `\n` to `\r\n`, which is what the Windows clipboard expects
+ * anyway.
+ *
+ * `setClipboardText` stays for a machine with no `clip.exe`.
  */
 export function copyText(text) {
   const s = String(text == null ? '' : text);
   if (!s) return false;
   if (win()) {
-    if (setClipboardText(s)) return true;
-    cp.execSync('clip', { input: Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(s, 'utf16le')]), windowsHide: true, timeout: 5000 });
-    return true;
+    // `clip.exe` FIRST, fed UTF-8 through a 65001 console.
+    //
+    // Measured 150-193ms at every size from 100 to 400000 characters, against 748-788ms for a PowerShell
+    // one-shot — and the PowerShell route puts the text on its COMMAND LINE, which Windows caps near 32KB, so
+    // a 20k-character copy failed outright with ENAMETOOLONG.
+    //
+    // THE ENCODING IS NOT UTF-16. `clip.exe` decodes stdin with the console code page, which is 936 (GBK) on a
+    // Chinese Windows: UTF-16LE bytes came back byte-swapped (`你好` U+4F60 U+597D arrived as U+604F U+597D)
+    // and UTF-8 bytes without the matching code page came back as mojibake. `chcp 65001` on the child and UTF-8
+    // in the pipe is what round-trips — verified on ASCII, Chinese, emoji and 400k characters.
+    //
+    // Synchronous, because the caller announces "Copied" the moment this returns.
+    const r = cp.spawnSync('cmd', ['/c', 'chcp 65001 >nul && clip'], {
+      input: Buffer.from(s, 'utf8'),
+      windowsHide: true,
+      timeout: 5000,
+    });
+    if (r && r.status === 0) return true;
+    return setClipboardText(s);
   }
   const cmd = process.platform === 'darwin' ? 'pbcopy' : 'xclip -selection clipboard';
   cp.execSync(cmd, { input: Buffer.from(s, 'utf8'), timeout: 5000 });
@@ -113,6 +131,41 @@ function setClipboardText(s) {
   return false;
 }
 
+/**
+ * Put text on the clipboard WITHOUT blocking the event loop.
+ *
+ * `copyText` is synchronous because most callers want to know the outcome before they say "Copied". A copy is
+ * 150-190ms of child process on Windows, which is long enough to be felt as a stutter when it runs between two
+ * paints. The TUI uses this where a reply is not needed.
+ *
+ * @param {string} text
+ * @returns {Promise<boolean>}
+ */
+export function copyTextAsync(text) {
+  const s = String(text == null ? '' : text);
+  if (!s) return Promise.resolve(false);
+  if (!win()) {
+    try { copyText(s); return Promise.resolve(true); } catch { return Promise.resolve(false); }
+  }
+  return new Promise((resolve) => {
+    try {
+      // Same command and encoding as `copyText`: the code page has to be set on the child, and the payload is
+      // UTF-8. See the note there for why UTF-16 does not work.
+      const child = cp.spawn('cmd', ['/c', 'chcp 65001 >nul && clip'], {
+        windowsHide: true,
+        stdio: ['pipe', 'ignore', 'ignore'],
+      });
+      child.on('error', () => resolve(false));
+      child.on('close', (code) => resolve(code === 0));
+      child.stdin.on('error', () => { /* a broken pipe is reported by `close` */ });
+      child.stdin.end(Buffer.from(s, 'utf8'));
+    } catch {
+      // No clip.exe: fall back to the blocking route rather than losing the copy.
+      try { resolve(setClipboardText(s)); } catch { resolve(false); }
+    }
+  });
+}
+
 // Which PowerShell the helper runs. `pwsh` (7) starts far faster than the built-in
 // `powershell` (5.1) — measured 1.9s vs 11.5s for the same image probe — and the image
 // path needs the WinForms/Drawing assemblies. This is only the PREFERRED name: it is
@@ -193,7 +246,13 @@ function startHelper(exe) {
   // unavailable" for a clipboard that had content. The queued resolver here is what
   // marks the shell as ready, so one sentinel still has exactly one owner.
   helperQueue.push(() => { helperReady = true; });
-  helper.stdin.write("try { Add-Type -AssemblyName System.Windows.Forms; Add-Type -AssemblyName System.Drawing } catch {}\n'" + SENT + "'\n");
+  // The sequence probe's P/Invoke declaration is compiled here too: the first `Add-Type` on a cold shell
+  // measured ~900ms, which is exactly the cost this warm-up exists to move off the paste path.
+  helper.stdin.write(
+    "try { Add-Type -AssemblyName System.Windows.Forms; Add-Type -AssemblyName System.Drawing } catch {}\n"
+    + "try { if(-not ('HnClip' -as [type])){Add-Type -Namespace '' -Name 'HnClip' -MemberDefinition '[DllImport(\"user32.dll\")] public static extern uint GetClipboardSequenceNumber();'} } catch {}\n"
+    + "'" + SENT + "'\n",
+  );
 }
 
 /** Tear down the helper and release every waiter. A read must never be left hanging on
@@ -249,7 +308,10 @@ function helperRun(script, timeoutMs) {
 function readOnce() {
   if (win()) {
     const b64 = runPowershell(
-      '-NoProfile -Command "[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes((Get-Clipboard -Raw) + \'\'))"',
+      // `Clipboard::GetText()` instead of `Get-Clipboard -Raw`: measured on a 20k-character text, the cmdlet
+      // took 169ms and the .NET call 13ms. `Get-Clipboard` goes through PowerShell's COM wrapper, which
+      // copies the string several times before it reaches the pipeline.
+      '-NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([System.Windows.Forms.Clipboard]::GetText() + \'\'))"',
       { encoding: 'ascii', windowsHide: true, timeout: ONESHOT_MS },
     );
     if (b64 == null) throw new Error('no powershell');
@@ -269,7 +331,7 @@ export async function readText(timeoutMs = HELPER_CMD_MS) {
     // warming is answered by nothing, and the cold path is the expensive one.
     if (helper && await waitHelperReady(HELPER_READY_MS)) {
       helperBusy = true;
-      const out = await helperRun('[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes((Get-Clipboard -Raw) + ""))', timeoutMs);
+      const out = await helperRun('[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([System.Windows.Forms.Clipboard]::GetText() + ""))', timeoutMs);
       if (out != null) {
         const b64 = out.replace(/\r/g, '').split('\n').filter((l) => l.trim()).pop() || '';
         try { return { text: Buffer.from(b64.trim(), 'base64').toString('utf8'), via: 'helper' }; } catch {}
@@ -301,7 +363,38 @@ export async function readText(timeoutMs = HELPER_CMD_MS) {
 // PowerShell expression (silently returned nothing), which made FILE pastes fall
 // back to the slow cold spawn. Emitting one F:: line per file is simpler and
 // also supports multi-file copies.
-//
+/**
+ * Just the clipboard's TEXT, or '' — no file list, no image.
+ *
+ * Asked before paying for a PNG: a browser's image copy carries the pixels AND the address, and only the text
+ * formats can hold that address. Cheap on the warm helper, which is already running by the time anyone pastes.
+ *
+ * @returns {Promise<string>}
+ */
+export async function readClipboardTextOnly() {
+  if (!win()) { try { return readOnce() || ''; } catch { return ''; } }
+  warmClipboard();
+  if (!helper) {
+    try { return readOnce() || ''; } catch { return ''; }
+  }
+  if (!helperReady && !await waitHelperReady(HELPER_READY_MS)) {
+    try { return readOnce() || ''; } catch { return ''; }
+  }
+  for (let i = 0; i < 20 && helperBusy; i++) await new Promise((r) => setTimeout(r, 25));
+  if (helperBusy || !helper) {
+    try { return readOnce() || ''; } catch { return ''; }
+  }
+  helperBusy = true;
+  let out;
+  try {
+    out = await helperRun(CLIP_PROBE_TEXT, HELPER_CMD_MS);
+  } finally {
+    helperBusy = false;
+  }
+  const line = String(out || '').split('\n').map((l) => l.trim()).find((l) => l.startsWith('T::'));
+  if (!line) return '';
+  try { return Buffer.from(line.slice(3), 'base64').toString('utf8'); } catch { return ''; }
+}
 // The image branch uses the .NET WinForms clipboard, NOT `Get-Clipboard -Image`:
 // that parameter only exists on some builds (and is absent even from the pwsh 7
 // in use here), so it silently failed everywhere and image paste never worked.
@@ -321,15 +414,24 @@ export async function readText(timeoutMs = HELPER_CMD_MS) {
  */
 const CLIP_PROBE_TEXT = [
   "$ErrorActionPreference='SilentlyContinue'",
-  "$t=Get-Clipboard -Raw",
+  // .NET, not the cmdlet: 13ms against 169ms on the same 20k-character text.
+  "$t=[System.Windows.Forms.Clipboard]::GetText()",
   "if($t){'T::'+[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($t))}",
 ].join('; ');
 
 const CLIP_PROBE = [
   "$ErrorActionPreference='SilentlyContinue'",
-  "$f=Get-Clipboard -Format FileDropList",
-  "if($f -and $f.Count -gt 0){$f|ForEach-Object{'F::'+$_.FullName};return}",
-  "$t=Get-Clipboard -Raw",
+  // FILES COME FROM THE .NET CLIPBOARD, not `Get-Clipboard -Format FileDropList`.
+  //
+  // That parameter does not exist in PowerShell 7 — `Get-Clipboard: A parameter cannot be found that matches
+  // parameter name 'Format'` — and the `SilentlyContinue` above turns the error into an empty result, so a
+  // copied file read as "clipboard unavailable" while copied text worked. `Clipboard::GetFileDropList()` is the
+  // same call on both versions; verified on the 5.1 build in System32 and on pwsh 7 here.
+  "Add-Type -AssemblyName System.Windows.Forms",
+  "$f=[System.Windows.Forms.Clipboard]::GetFileDropList()",
+  "if($f -and $f.Count -gt 0){$f|ForEach-Object{'F::'+$_};return}",
+  // .NET, not the cmdlet: 13ms against 169ms on the same 20k-character text.
+  "$t=[System.Windows.Forms.Clipboard]::GetText()",
   "if($t){'T::'+[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($t));return}",
   // The assemblies are loaded once by warmClipboard(); no Add-Type here, so the
   // probe stays fast even the first time an image is on the clipboard.
@@ -337,6 +439,22 @@ const CLIP_PROBE = [
   "if($null -ne $i){$p=Join-Path $env:TEMP ('hncode-paste-'+[guid]::NewGuid().ToString('N')+'.png');$i.Save($p,[System.Drawing.Imaging.ImageFormat]::Png);'I::'+$p}",
 ].join('; ');
 
+/**
+ * The clipboard's sequence number, one integer.
+ *
+ * Windows bumps it on every clipboard write, so comparing two readings answers "did the content change"
+ * without reading the content. `Get-Clipboard` has no equivalent, so this P/Invokes `user32` — once, because
+ * the type stays compiled for the life of the warm shell.
+ *
+ * A real read costs time proportional to the payload (measured: 14ms at 1k characters, 48ms at 400k); this
+ * does not, which is what makes a repeat paste of a long text instant.
+ */
+const CLIP_SEQ_PROBE = [
+  "$ErrorActionPreference='SilentlyContinue'",
+  "if(-not ('HnClip' -as [type])){Add-Type -Namespace '' -Name 'HnClip' -MemberDefinition '[DllImport(\"user32.dll\")] public static extern uint GetClipboardSequenceNumber();'}",
+  "'S::'+[HnClip]::GetClipboardSequenceNumber()",
+].join('; ');
+
 // Parse the probe output into { text, via }. Handles one-or-more F:: lines.
 function parseClipResult(out) {
   const lines = String(out == null ? '' : out).replace(/\r/g, '').split('\n').map((l) => l.trim()).filter(Boolean);
@@ -353,6 +471,38 @@ function parseClipResult(out) {
   return null;
 }
 
+/**
+ * A URL hidden in the TEXT of a copied image, or null.
+ *
+ * Copying an image out of a browser puts several formats on the clipboard at once: the pixels, an HTML
+ * fragment (`<img src="…">`, sometimes a `data:` URL) and, for a plain image, the image's own address. The
+ * pixel route costs a PNG written to disk for something the model can fetch directly — so the text formats
+ * are checked FIRST and only a clipboard with no address at all becomes a file.
+ *
+ * Only http(s) and `data:` are accepted. A `file:` URL is the same thing as a copied file, which the file
+ * drop list already covers.
+ *
+ * @param {string} text The clipboard's text, possibly an HTML fragment.
+ * @returns {string|null}
+ */
+export function imageUrlFromClipboardText(text) {
+  const s = String(text || '').trim();
+  if (!s) return null;
+  // A bare URL: the image's own address was copied.
+  const bare = /^(https?:\/\/\S+|data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=\s]+)$/i.exec(s);
+  if (bare) return bare[1].replace(/\s+/g, '').trim();
+  // An HTML fragment: take the src of the first <img>, which is what a browser's image copy produces.
+  const img = /<img\b[^>]*\bsrc\s*=\s*("([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(s);
+  if (img) {
+    const url = (img[2] || img[3] || img[4] || '').trim();
+    if (/^(https?:\/\/|data:image\/)/i.test(url)) return url.replace(/\s+/g, '');
+  }
+  // A plain address on its own line inside a longer text selection.
+  const line = s.split(/\r?\n/).map((l) => l.trim())
+    .find((l) => /^https?:\/\/\S+\.(png|jpe?g|gif|webp|bmp|svg)(\?\S*)?$/i.test(l));
+  return line || null;
+}
+
 // ---- pasted-image lifecycle ------------------------------------------------
 // A pasted image is written to a temp .png (the model needs a PATH to hand to
 // ReadMediaFile), so something has to remove it again or the temp dir fills up
@@ -442,14 +592,49 @@ export function readClipboardContent() {
   return parseClipResult(out) || { text: '', via: 'none' };
 }
 
+// ---- the fast path's memory --------------------------------------------------
+//
+// `GetClipboardSequenceNumber` is one integer, and Windows bumps it on every clipboard write. Asking the
+// helper for it is a single cheap call; when it matches the last read, the previous result is returned without
+// touching the clipboard at all. That is what makes a repeat paste instant regardless of how long the text is —
+// the read cost scaled with the payload, but the sequence check does not.
+let lastSeq = null;
+let lastResult = null;
+/** The sequence number alone, read on the warm helper. Null when it is not available. */
+async function readClipboardSequence() {
+  warmClipboard();
+  if (!helper) return null;
+  if (!helperReady && !await waitHelperReady(HELPER_READY_MS)) return null;
+  if (helperBusy) return null;               // somebody is mid-command; the caller can just read normally
+  helperBusy = true;
+  let out;
+  try {
+    out = await helperRun(CLIP_SEQ_PROBE, HELPER_CMD_MS);
+  } finally {
+    helperBusy = false;
+  }
+  const line = String(out || '').split('\n').map((l) => l.trim()).find((l) => l.startsWith('S::'));
+  if (!line) return null;
+  const n = Number(line.slice(3));
+  return Number.isFinite(n) ? n : null;
+}
+
 // Async version that prefers the warm helper (~10ms) over a cold spawn (~2.9s).
 export async function readClipboardContentAsync() {
   if (!win()) {
     try { return { text: readOnce(), via: 'oneshot' }; } catch { return { text: '', via: 'none' }; }
   }
+  // A CLIPBOARD THAT HAS NOT CHANGED IS NOT READ AGAIN.
+  //
+  // The measured cost of a read is dominated by the payload (14ms for 1k characters, 48ms for 400k) and the
+  // user pays it on every paste even when the clipboard holds the same thing. The sequence number answers "did
+  // it change" in one cheap call, so a repeat paste of the same large text is instant.
+  const seq = await readClipboardSequence();
+  if (seq !== null && seq === lastSeq && lastResult) return { ...lastResult };
   const viaHelper = await readViaHelper();
-  if (viaHelper) return viaHelper;
-  return readClipboardContent();
+  const result = viaHelper || readClipboardContent();
+  if (seq !== null) { lastSeq = seq; lastResult = result; }
+  return result;
 }
 
 // The PowerShell logic for the one-shot fallback lives in a temp .ps1 file:
@@ -461,13 +646,16 @@ function clipScriptPath() {
   const p = path.join(os.tmpdir(), 'hncode-clipread.ps1');
   const script = [
     "$ErrorActionPreference = 'SilentlyContinue'",
-    '$files = Get-Clipboard -Format FileDropList',
-    'if ($files -and $files.Count -gt 0) { $files | ForEach-Object { "F::" + $_.FullName }; exit }',
-    '$txt = Get-Clipboard -Raw',
-    'if ($txt) { "T::" + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($txt)); exit }',
-    // .NET clipboard, not `Get-Clipboard -Image` (see the CLIP_PROBE note).
+    // .NET clipboard for BOTH files and images. `Get-Clipboard -Format FileDropList` is missing from
+    // PowerShell 7, and with SilentContinue that turned a copied file into "nothing on the clipboard".
     'Add-Type -AssemblyName System.Windows.Forms',
     'Add-Type -AssemblyName System.Drawing',
+    '$files = [System.Windows.Forms.Clipboard]::GetFileDropList()',
+    'if ($files -and $files.Count -gt 0) { $files | ForEach-Object { "F::" + $_ }; exit }',
+    // .NET, not the cmdlet: the cmdlet copies the string several times before the pipeline sees it.
+    '$txt = [System.Windows.Forms.Clipboard]::GetText()',
+    'if ($txt) { "T::" + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($txt)); exit }',
+    // .NET clipboard, not `Get-Clipboard -Image` (see the CLIP_PROBE note).
     '$img = [System.Windows.Forms.Clipboard]::GetImage()',
     'if ($null -ne $img) {',
     '  $path = Join-Path $env:TEMP ("hncode-paste-" + [guid]::NewGuid().ToString("N") + ".png")',

package/src/tools/goal.js

@@ -0,0 +1,93 @@
+/**
+ * The Goal tool: the agent's own objective across turns.
+ *
+ * A turn ends when the model stops. Some work does not fit in one turn — a refactor across a dozen files, a
+ * migration, a suite that needs several rounds — and without a goal the agent simply stops halfway and waits
+ * to be told to continue. The goal makes that explicit: a line the agent wrote for itself, shown in the status
+ * panel, and the turn loop restarts the agent while one is set.
+ *
+ * ONE STORE, NOT TWO. The objective lives in the TUI's `state.objective` — the same field `/goal` writes — and
+ * this module only borrows it through a listener. A second copy here would drift the moment the user typed
+ * `/goal cancel`, and the loop would restart against an objective nobody could see.
+ *
+ * THREE ACTIONS:
+ *
+ *   set      Start or replace the objective.
+ *   status   Read it back, so a resumed turn can re-read what it was doing.
+ *   clear    Finish. Nothing restarts after this, which is why it has to be deliberate.
+ */
+
+/** Read the goal. Installed by startTUI, backed by `state.objective`. */
+let readGoal = () => '';
+/** Write the goal. Installed by startTUI. */
+let writeGoal = () => {};
+
+/**
+ * @param {{get: () => string, set: (goal: string) => void}} api
+ */
+export function installGoalStore(api) {
+  if (api && typeof api.get === 'function') readGoal = api.get;
+  if (api && typeof api.set === 'function') writeGoal = api.set;
+}
+
+/** The current objective, or ''. */
+export function getGoal() {
+  try { return String(readGoal() || '').trim(); } catch { return ''; }
+}
+
+export const spec = {
+  name: 'Goal',
+  description: [
+    'Set, read or clear the objective you are working towards across turns.',
+    '',
+    'A turn ends when you stop responding. While a goal is set the agent restarts you with it quoted back, so',
+    'use it for work that genuinely needs several turns — not for something you can finish now.',
+    '',
+    '- set: start or replace it. Write a finishable outcome ("all callers of X migrated and the suite passes"),',
+    '  not an activity ("work on X").',
+    '- status: read it back.',
+    '- clear: you are done. Call this the moment the goal is met; otherwise the loop restarts you again.',
+    '',
+    'The user can set the same goal with /goal and can pause it. Never clear a goal you have not met.',
+  ].join('\n'),
+  parameters: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['set', 'status', 'clear'],
+        description: 'set = start or replace, status = read back, clear = finished.',
+      },
+      goal: {
+        type: 'string',
+        description: 'The objective. Required for `set`; a finishable outcome, not an activity.',
+      },
+    },
+    required: ['action'],
+  },
+
+  /**
+   * @param {{action: string, goal?: string}} args
+   * @returns {string}
+   */
+  execute(args) {
+    const action = String((args && args.action) || '').toLowerCase();
+    if (action === 'set') {
+      const goal = String((args && args.goal) || '').trim();
+      if (!goal) return 'Error: `set` needs a goal — the outcome you are working towards.';
+      try { writeGoal(goal); } catch { return 'Error: could not store the goal.'; }
+      return `Goal set: ${goal}\nThe turn loop restarts you with this until you call Goal with action clear.`;
+    }
+    if (action === 'status') {
+      const goal = getGoal();
+      return goal ? `Goal: ${goal}` : 'No goal is set.';
+    }
+    if (action === 'clear') {
+      const goal = getGoal();
+      if (!goal) return 'No goal to clear.';
+      try { writeGoal(''); } catch { return 'Error: could not clear the goal.'; }
+      return `Goal cleared: ${goal}\nNothing will restart this turn now.`;
+    }
+    return `Error: unknown action "${args && args.action}". Use set, status or clear.`;
+  },
+};

package/src/tools/index.js

@@ -22,6 +22,7 @@ import { TEAM_TOOL_SPECS } from './team.js';
 import { spec as notebookSpec } from './notebook.js';
 import { spec as diagnosticsSpec } from './diagnostics.js';
 import * as memoryMod from './memory.js';
+import * as goalMod from './goal.js';
 import { pluginTools, pluginToolGeneration } from '../plugin.js';
 
 
@@ -55,6 +56,7 @@ const builtinTools = [
   notebookSpec,
   diagnosticsSpec,
   memoryMod.spec,
+  goalMod.spec,
   ...TEAM_TOOL_SPECS,
 ];