@vectorize-io/hindsight-coding-agents 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +137 -13
  2. package/dist/antigravity-hook.js +711 -55
  3. package/dist/antigravity-statusline.js +68 -7
  4. package/dist/antigravity-stop-hook.js +771 -57
  5. package/dist/claude-hook.js +711 -55
  6. package/dist/claude-sessionstart-hook.js +789 -68
  7. package/dist/claude-stop-hook.js +771 -57
  8. package/dist/cline.js +295 -75
  9. package/dist/codex-hook.js +711 -55
  10. package/dist/codex-sessionstart-hook.js +789 -68
  11. package/dist/codex-stop-hook.js +771 -57
  12. package/dist/copilot-hook.js +711 -55
  13. package/dist/copilot-sessionstart-hook.js +789 -68
  14. package/dist/copilot-stop-hook.js +771 -57
  15. package/dist/cursor-hook.js +711 -55
  16. package/dist/cursor-sessionstart-hook.js +789 -68
  17. package/dist/cursor-stop-hook.js +771 -57
  18. package/dist/daemon-start.js +38 -1
  19. package/dist/dcode-hook.js +711 -55
  20. package/dist/dcode-sessionstart-hook.js +789 -68
  21. package/dist/dcode-stop-hook.js +771 -57
  22. package/dist/deepen.js +236 -61
  23. package/dist/devin-hook.js +711 -55
  24. package/dist/devin-sessionstart-hook.js +789 -68
  25. package/dist/devin-stop-hook.js +771 -57
  26. package/dist/droid-hook.js +711 -55
  27. package/dist/droid-sessionstart-hook.js +789 -68
  28. package/dist/droid-stop-hook.js +771 -57
  29. package/dist/dsh.js +296 -76
  30. package/dist/grok-hook.js +711 -55
  31. package/dist/grok-sessionstart-hook.js +789 -68
  32. package/dist/grok-stop-hook.js +771 -57
  33. package/dist/hindsight-seed.js +41 -4
  34. package/dist/index.js +295 -75
  35. package/dist/installer.js +1148 -303
  36. package/dist/kilo.js +295 -75
  37. package/dist/kimi-hook.js +3909 -0
  38. package/dist/kimi-sessionstart-hook.js +4650 -0
  39. package/dist/kimi-stop-hook.js +4218 -0
  40. package/dist/mcp-server.js +162 -33
  41. package/dist/opencode2.js +298 -76
  42. package/dist/pi.js +299 -75
  43. package/dist/prime-agent.js +299 -75
  44. package/dist/qwen-hook.js +711 -55
  45. package/dist/qwen-sessionstart-hook.js +789 -68
  46. package/dist/qwen-stop-hook.js +771 -57
  47. package/dist/status.js +132 -14
  48. package/dist/traecode-hook.js +3909 -0
  49. package/dist/traecode-sessionstart-hook.js +4650 -0
  50. package/dist/traecode-stop-hook.js +4218 -0
  51. package/dist/zcode-hook.js +711 -55
  52. package/dist/zcode-sessionstart-hook.js +789 -68
  53. package/dist/zcode-stop-hook.js +771 -57
  54. package/package.json +15 -11
  55. package/plugin.json +1 -1
  56. package/skill/SKILL.md +70 -11
package/dist/kilo.js CHANGED
@@ -312,13 +312,13 @@ function isWithin(directory, configured) {
312
312
  function mapLookup(map3, directory) {
313
313
  const cwd = normalize(directory);
314
314
  let best;
315
- for (const [dir, bank] of Object.entries(map3)) {
315
+ for (const [dir, value] of Object.entries(map3)) {
316
316
  const p = configuredDir(dir);
317
317
  if (isWithin(cwd, p)) {
318
- if (!best || p.length > best.len) best = { len: p.length, bank };
318
+ if (!best || p.length > best.len) best = { len: p.length, value };
319
319
  }
320
320
  }
321
- return best?.bank;
321
+ return best?.value;
322
322
  }
323
323
  function lookupDirectories(config3, directory, sessionRoot = "") {
324
324
  const directories = [normalize(directory)];
@@ -342,6 +342,10 @@ function isOptedIn(config3, directory) {
342
342
  const pathMap = config3.mapPathToBank;
343
343
  return Boolean(pathMap && directories.some((candidate) => mapLookup(pathMap, candidate)));
344
344
  }
345
+ function pathSection(config3, paths, directory) {
346
+ if (!directory || !paths) return void 0;
347
+ return lookupDirectories(config3, directory).map((candidate) => mapLookup(paths, candidate)).find((section) => section !== void 0);
348
+ }
345
349
  function mappedBank(config3, directory, sessionRoot) {
346
350
  const pathMap = config3.mapPathToBank;
347
351
  if (!directory || !pathMap) return void 0;
@@ -589,12 +593,17 @@ var CODING_BANK_TEMPLATE = {
589
593
  }
590
594
  };
591
595
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
596
+ var PLUGIN_GOVERNED_BANK_FIELDS = [
597
+ "retain_strategies",
598
+ "entity_labels",
599
+ "retain_extraction_mode"
600
+ ];
592
601
  function isSet(v) {
593
602
  if (v === null || v === void 0) return false;
594
603
  if (typeof v === "string") return v.trim() !== "";
595
604
  return true;
596
605
  }
597
- function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
606
+ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE, defaults = {}) {
598
607
  const current2 = overrides ?? {};
599
608
  const template = CODING_BANK_TEMPLATE.bank;
600
609
  const bank = {};
@@ -623,6 +632,10 @@ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
623
632
  const [knowledgeGroup] = template.entity_labels;
624
633
  if (!labels.some((g) => g?.key === knowledgeGroup.key))
625
634
  bank.entity_labels = [...labels, knowledgeGroup];
635
+ for (const [key, value] of Object.entries(defaults)) {
636
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key) || !isSet(value) || isSet(current2[key])) continue;
637
+ bank[key] = value;
638
+ }
626
639
  return Object.keys(bank).length > 0 ? { version: "1", bank } : void 0;
627
640
  }
628
641
 
@@ -745,6 +758,18 @@ var DEFAULT_RECALL_OPTIONS = {
745
758
  var POLL_CYCLE_MS = 5e3;
746
759
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
747
760
  var RETRY_AFTER_CEILING_MS = 60 * 1e3;
761
+ function shapePage(page) {
762
+ const p = page ?? {};
763
+ const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
764
+ return {
765
+ id: p.id,
766
+ name: p.name,
767
+ ...p.description ? { description: p.description } : {},
768
+ ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
769
+ ...p.timestamp ? { last_updated_at: p.timestamp } : {},
770
+ body
771
+ };
772
+ }
748
773
  var HindsightClient = class {
749
774
  apiUrl;
750
775
  /** The credential the NEXT request will sign with — NOT the one the config file holds. The two
@@ -782,7 +807,10 @@ var HindsightClient = class {
782
807
  return this.token;
783
808
  }
784
809
  headers() {
785
- const h = { "Content-Type": "application/json" };
810
+ const h = {
811
+ "Content-Type": "application/json",
812
+ "Accept-Encoding": "identity"
813
+ };
786
814
  if (this.token) h["Authorization"] = `Bearer ${this.token}`;
787
815
  return h;
788
816
  }
@@ -890,6 +918,23 @@ var HindsightClient = class {
890
918
  return false;
891
919
  }
892
920
  }
921
+ /**
922
+ * Whether a session write-back may use `update_mode="append"`: the server must dedupe by
923
+ * `operation_id` AND the bank must keep document text, or the server rejects the append in the
924
+ * background (#4613). Only an explicit `store_document_text: false` answers "no" — an unreachable
925
+ * or unparseable config assumes the default (stored), so a flaky probe never downgrades appends.
926
+ */
927
+ async supportsAppendRetain() {
928
+ if (!await this.supportsIdempotentRetain()) return false;
929
+ try {
930
+ const r = await this.req("GET", this.bankUrl("/config"));
931
+ if (!r.ok) return true;
932
+ const j = await r.json();
933
+ return j.config?.store_document_text !== false;
934
+ } catch {
935
+ return true;
936
+ }
937
+ }
893
938
  /**
894
939
  * Every document_id currently in the bank under a strategy tag (e.g. `source:git`), paginated into a
895
940
  * Set. Powers the incremental git-sync's "what's already ingested?" check — since git commits are stored
@@ -915,6 +960,24 @@ var HindsightClient = class {
915
960
  }
916
961
  return ids;
917
962
  }
963
+ /**
964
+ * The tags on one document, or undefined when the bank holds none with that id. Read from the
965
+ * document LISTING narrowed by `q` (a substring match on the id, so the exact id is picked out of
966
+ * the page) rather than GET /documents/{id}, which also sends the document's full text: the
967
+ * caller, the git-log freshness check on SessionStart, reads a ~100k-character document for one tag.
968
+ */
969
+ async documentTags(documentId) {
970
+ const limit = 100;
971
+ for (let offset = 0; ; offset += limit) {
972
+ const q = `?q=${encodeURIComponent(documentId)}&limit=${limit}&offset=${offset}`;
973
+ const r = await this.req("GET", this.bankUrl(`/documents${q}`));
974
+ const j = await r.json();
975
+ const items = j.items ?? [];
976
+ const hit = items.find((it) => it.id === documentId);
977
+ if (hit) return hit.tags ?? [];
978
+ if (items.length < limit || offset + limit >= (j.total ?? 0)) return void 0;
979
+ }
980
+ }
918
981
  /** Configure the bank: POST the coding bank manifest to /import (missions, retain strategies,
919
982
  * entity labels), then seed knowledge pages when the server supports them. Both halves are
920
983
  * idempotent and ADDITIVE — nothing the bank already says is overwritten (#3927), bar the
@@ -936,7 +999,8 @@ var HindsightClient = class {
936
999
  } else {
937
1000
  const manifest = codingBankManifest(
938
1001
  opts.reset ? void 0 : await this.readBankOverrides(),
939
- opts.extractionMode
1002
+ opts.extractionMode,
1003
+ opts.defaults
940
1004
  );
941
1005
  if (!manifest) {
942
1006
  this.log(`[bank] ${this.bank} already carries the coding structure \u2014 nothing to apply`);
@@ -1142,8 +1206,8 @@ var HindsightClient = class {
1142
1206
  return { items };
1143
1207
  }
1144
1208
  /**
1145
- * Read one knowledge page's synthesized content by knowledge-base id, as an OKF document
1146
- * (YAML frontmatter + markdown body). The endpoint omits the internal reflect trace that built
1209
+ * Read one knowledge page's synthesized content by knowledge-base id, shaped by `shapePage` so
1210
+ * the body arrives once. The endpoint omits the internal reflect trace that built
1147
1211
  * the page — that is 70-95% of the raw bytes and can blow past an MCP host's per-tool-result
1148
1212
  * token cap.
1149
1213
  */
@@ -1154,7 +1218,7 @@ var HindsightClient = class {
1154
1218
  this.bankUrl(`/knowledge-base/pages/${encodeURIComponent(pageId)}`)
1155
1219
  );
1156
1220
  if (r.status === 404) throw new Error(`knowledge page not found: ${pageId}`);
1157
- return await r.json();
1221
+ return shapePage(await r.json());
1158
1222
  }
1159
1223
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
1160
1224
  * Returns page-level hits with a relevance snippet — the real search behind
@@ -1175,6 +1239,7 @@ var HindsightClient = class {
1175
1239
  return (j.results ?? []).map((x) => ({
1176
1240
  id: x.id,
1177
1241
  name: x.name,
1242
+ ...x.source_query ? { source_query: x.source_query } : {},
1178
1243
  snippet: x.snippet ?? "",
1179
1244
  score: x.score ?? 0
1180
1245
  }));
@@ -1445,6 +1510,7 @@ function resolveCustomPages(raw) {
1445
1510
  }
1446
1511
  var DEFAULT_REFLECT_TIMEOUT_MS = 2e4;
1447
1512
  var DEFAULT_REFLECT_TOOL_TIMEOUT_MS = 33e4;
1513
+ var DEFAULT_INJECT_TIMEOUT_MS = 7e3;
1448
1514
  var REFLECT_BUDGETS = ["low", "mid", "high"];
1449
1515
  function resolveReflectBudget(raw) {
1450
1516
  const value = raw.reflectBudget;
@@ -1471,6 +1537,22 @@ function resolveObservationScopes(raw) {
1471
1537
  }
1472
1538
  return DEFAULT_OBSERVATION_SCOPES;
1473
1539
  }
1540
+ function resolveDefaultBankConfig(raw) {
1541
+ const value = raw;
1542
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
1543
+ const out = {};
1544
+ for (const [key, v] of Object.entries(value)) {
1545
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key)) {
1546
+ log.warn(
1547
+ "config",
1548
+ `ignoring defaultBankConfig.${key} \u2014 the plugin manages this field itself` + (key === "retain_extraction_mode" ? " (set retainExtractionMode instead)" : "")
1549
+ );
1550
+ continue;
1551
+ }
1552
+ out[key] = v;
1553
+ }
1554
+ return out;
1555
+ }
1474
1556
  var AUTO_INJECT_MODES = ["reflect", "pages", "recall", "none"];
1475
1557
  function resolveAutoInject(raw) {
1476
1558
  if (raw.autoReflect !== void 0) {
@@ -1510,18 +1592,21 @@ function resolveConfig(raw = {}) {
1510
1592
  // write sessions back by default, every harness
1511
1593
  manageBankConfig: raw.manageBankConfig ?? true,
1512
1594
  retainExtractionMode: RETAIN_EXTRACTION_MODES.includes(raw.retainExtractionMode) ? raw.retainExtractionMode : DEFAULT_RETAIN_EXTRACTION_MODE,
1595
+ defaultBankConfig: resolveDefaultBankConfig(raw.defaultBankConfig),
1513
1596
  maxParallelRetains: raw.maxParallelRetains || 10,
1514
1597
  reflectTimeoutMs: raw.reflectTimeoutMs || DEFAULT_REFLECT_TIMEOUT_MS,
1515
1598
  // Inherit an explicitly-raised reflectTimeoutMs (that is what users reaching for a longer
1516
1599
  // reflect already set), but never let it LOWER the tool below the default — a short window is
1517
1600
  // set to bound the automatic hook, not to cut off a call the agent is waiting on.
1518
1601
  reflectToolTimeoutMs: raw.reflectToolTimeoutMs || Math.max(raw.reflectTimeoutMs || 0, DEFAULT_REFLECT_TOOL_TIMEOUT_MS),
1602
+ injectTimeoutMs: raw.injectTimeoutMs || DEFAULT_INJECT_TIMEOUT_MS,
1519
1603
  reflectBudget: resolveReflectBudget(raw),
1520
1604
  autoInject: resolveAutoInject(raw),
1521
1605
  pageSearchLimit: raw.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT,
1522
1606
  // Same shape as retainMetadata: an object, or nothing. An array would spread into numeric
1523
1607
  // keys and reach the API as garbage, so it is rejected like any other non-object.
1524
1608
  recallOptions: raw.recallOptions && typeof raw.recallOptions === "object" && !Array.isArray(raw.recallOptions) ? { ...raw.recallOptions } : {},
1609
+ toolGuideExtra: typeof raw.toolGuideExtra === "string" && raw.toolGuideExtra.trim() ? raw.toolGuideExtra : void 0,
1525
1610
  // Every turn, not every tenth. The guide is what tells the agent WHEN to reach for memory, and
1526
1611
  // at a cadence of 10 a normal session is told once, on turn 1, and never again. Measured over
1527
1612
  // 40 real Claude Code turns, moving this from 10 to 1 took searches from 15% of turns to 32.5%
@@ -1541,11 +1626,15 @@ function resolveConfig(raw = {}) {
1541
1626
  // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
1542
1627
  // nested object cannot reach the API as a tag and fail the whole retain.
1543
1628
  retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
1629
+ // Undefined, not "", when unset or blank: the retain call distinguishes "not configured" (use
1630
+ // the built-in default) from a configured value, and an empty context would strip the default.
1631
+ retainContext: typeof raw.retainContext === "string" && raw.retainContext.trim() !== "" ? raw.retainContext : void 0,
1544
1632
  retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
1545
1633
  Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
1546
1634
  ) : {},
1547
1635
  observationScopes: resolveObservationScopes(raw.observationScopes),
1548
1636
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
1637
+ paths: raw.paths && typeof raw.paths === "object" ? raw.paths : {},
1549
1638
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info",
1550
1639
  autoUpdate: raw.autoUpdate ?? true
1551
1640
  };
@@ -1562,7 +1651,12 @@ function readRaw(path) {
1562
1651
  }
1563
1652
  function mergeRaw(a, b) {
1564
1653
  const { harnesses: _drop, ...flat } = b;
1565
- return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
1654
+ return {
1655
+ ...a,
1656
+ ...flat,
1657
+ banks: { ...a.banks ?? {}, ...b.banks ?? {} },
1658
+ paths: { ...a.paths ?? {}, ...b.paths ?? {} }
1659
+ };
1566
1660
  }
1567
1661
  function applyLayer(raw, layer, harness) {
1568
1662
  let out = mergeRaw(raw, layer);
@@ -1593,9 +1687,11 @@ var ENV_KEYS = {
1593
1687
  maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
1594
1688
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
1595
1689
  reflectToolTimeoutMs: "HINDSIGHT_REFLECT_TOOL_TIMEOUT_MS",
1690
+ injectTimeoutMs: "HINDSIGHT_INJECT_TIMEOUT_MS",
1596
1691
  reflectBudget: "HINDSIGHT_REFLECT_BUDGET",
1597
1692
  autoInject: "HINDSIGHT_AUTO_INJECT",
1598
1693
  pageSearchLimit: "HINDSIGHT_PAGE_SEARCH_LIMIT",
1694
+ toolGuideExtra: "HINDSIGHT_TOOL_GUIDE_EXTRA",
1599
1695
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
1600
1696
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
1601
1697
  pageTriggerType: "HINDSIGHT_PAGE_TRIGGER_TYPE",
@@ -1637,6 +1733,7 @@ var ENV_NUMBERS = /* @__PURE__ */ new Set([
1637
1733
  "maxParallelRetains",
1638
1734
  "reflectTimeoutMs",
1639
1735
  "reflectToolTimeoutMs",
1736
+ "injectTimeoutMs",
1640
1737
  "pageSearchLimit",
1641
1738
  "pageRefreshEveryTurns",
1642
1739
  "seedLimit",
@@ -1685,15 +1782,25 @@ var BANK_OVERRIDE_EXCLUDED = [
1685
1782
  function applyBankConfig(cfg, resolvedId, directory) {
1686
1783
  if (directory !== void 0 && !isOptedIn(cfg, directory))
1687
1784
  return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
1785
+ const byPath = directory === void 0 ? void 0 : pathSection(cfg, cfg.paths, directory);
1786
+ if (byPath) {
1787
+ const { bank: _rename, ...rest } = overrideFields(byPath);
1788
+ cfg = { ...cfg, ...resolvePartial(cfg, rest) };
1789
+ }
1688
1790
  const section = cfg.banks[resolvedId];
1689
1791
  if (!section) return { cfg, bankId: resolvedId };
1690
- const safe = { ...section };
1691
- for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1692
- delete safe.banks;
1792
+ const safe = overrideFields(section);
1693
1793
  const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
1694
1794
  delete safe.bank;
1695
1795
  return { cfg: { ...cfg, ...resolvePartial(cfg, safe) }, bankId };
1696
1796
  }
1797
+ function overrideFields(section) {
1798
+ const safe = { ...section };
1799
+ for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1800
+ delete safe.banks;
1801
+ delete safe.paths;
1802
+ return safe;
1803
+ }
1697
1804
  function resolvePartial(cfg, patch) {
1698
1805
  const full = resolveConfig(patch);
1699
1806
  const out = {};
@@ -1702,6 +1809,16 @@ function resolvePartial(cfg, patch) {
1702
1809
  out[key] = full[key];
1703
1810
  }
1704
1811
  if ("autoReflect" in patch && !("autoInject" in patch)) out.autoInject = full.autoInject;
1812
+ if ("serverMode" in patch || "apiUrl" in patch || "apiPort" in patch) {
1813
+ const conn = resolveConfig({
1814
+ serverMode: patch.serverMode ?? cfg.serverMode,
1815
+ apiPort: patch.apiPort ?? cfg.apiPort,
1816
+ apiUrl: patch.apiUrl ?? (cfg.serverMode === "daemon" ? void 0 : cfg.apiUrl)
1817
+ });
1818
+ out.serverMode = conn.serverMode;
1819
+ out.apiUrl = conn.apiUrl;
1820
+ out.apiPort = conn.apiPort;
1821
+ }
1705
1822
  return out;
1706
1823
  }
1707
1824
 
@@ -1730,7 +1847,12 @@ function resolveHostMemory(harness, directory) {
1730
1847
  // rotate the key mid-session and the snapshot 401s every call until restart (#3600). Read
1731
1848
  // through the same pipeline the constructor used, so a per-bank `banks.<id>.apiToken` is
1732
1849
  // honoured on re-resolution exactly as it was on the first one.
1733
- tokenProvider: () => resolveHostConfig(harness, directory).cfg.apiToken
1850
+ // The URL stays the one this client was built with, so a token re-read after the config
1851
+ // moved this directory to ANOTHER server is that server's credential: never send it here.
1852
+ tokenProvider: () => {
1853
+ const live = resolveHostConfig(harness, directory).cfg;
1854
+ return live.apiUrl === cfg.apiUrl ? live.apiToken : cfg.apiToken;
1855
+ }
1734
1856
  })
1735
1857
  };
1736
1858
  }
@@ -2056,12 +2178,46 @@ function startDaemonDetached(cfg, harness, spawnFn = realSpawn3) {
2056
2178
  } catch {
2057
2179
  }
2058
2180
  }
2181
+ var coldStarts = /* @__PURE__ */ new Map();
2182
+ async function waitBounded(p, ms) {
2183
+ let timer;
2184
+ try {
2185
+ await Promise.race([
2186
+ p,
2187
+ new Promise((resolve3) => {
2188
+ timer = setTimeout(resolve3, Math.max(ms, 0));
2189
+ })
2190
+ ]);
2191
+ } finally {
2192
+ clearTimeout(timer);
2193
+ }
2194
+ }
2059
2195
  async function ensureDaemon(cfg, harness, opts = {}) {
2060
2196
  if (cfg.serverMode !== "daemon") return;
2061
2197
  if (await isServerHealthy(cfg.apiUrl)) return;
2062
2198
  if (!preflightDaemon(cfg, harness)) return;
2063
- startDaemonDetached(cfg, harness, opts.spawnFn);
2064
- await waitForHealth(cfg.apiUrl, opts.waitMs ?? 0);
2199
+ const waitMs = opts.waitMs ?? 0;
2200
+ const running = coldStarts.get(cfg.apiUrl);
2201
+ if (running) {
2202
+ const startedAt = Date.now();
2203
+ await waitBounded(
2204
+ running.catch(() => void 0),
2205
+ waitMs
2206
+ );
2207
+ const remaining = waitMs - (Date.now() - startedAt);
2208
+ if (remaining > 0) await waitForHealth(cfg.apiUrl, remaining);
2209
+ return;
2210
+ }
2211
+ const attempt = (async () => {
2212
+ startDaemonDetached(cfg, harness, opts.spawnFn);
2213
+ await waitForHealth(cfg.apiUrl, waitMs);
2214
+ })();
2215
+ coldStarts.set(cfg.apiUrl, attempt);
2216
+ try {
2217
+ await attempt;
2218
+ } finally {
2219
+ if (coldStarts.get(cfg.apiUrl) === attempt) coldStarts.delete(cfg.apiUrl);
2220
+ }
2065
2221
  }
2066
2222
  async function waitForHealth(baseUrl, budgetMs, pollMs = 1e3) {
2067
2223
  const deadline = Date.now() + budgetMs;
@@ -2113,13 +2269,13 @@ function indexLine(pages) {
2113
2269
  const count = pages.length === 1 ? "1 knowledge page covers" : `${pages.length} knowledge pages cover`;
2114
2270
  return `${count} this repository \u2014 architecture, conventions, past decisions and in-flight initiatives. They are deliberately NOT listed here: call hindsight_search_knowledge_pages(query) to find the ones that bear on the current turn, then hindsight_read_knowledge_page(<id>) on anything the results show is worth reading in full.`;
2115
2271
  }
2116
- var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, and the way IN to everything below. The code shows what is true today, never what was decided or why, so work built from code alone quietly re-litigates settled questions. Search BEFORE you act whenever the turn is one of these \u2014 they are the ones that go wrong silently:
2117
- \u2022 the user reports a bug or a wrong response (the intended behaviour, and the status code or value it should return, is usually already decided);
2272
+ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, and the way IN to everything below. The code shows what is true today but not what was decided or why; memory shows what was decided or said back then but not whether it still holds. Work built from either alone goes wrong: from code alone it quietly re-litigates settled questions, from memory alone it acts on stale claims. Search BEFORE you act whenever the turn is one of these \u2014 they are the ones that go wrong silently:
2273
+ \u2022 the user reports a bug or a wrong response (the intended behaviour, and the status code or value it should return, may already have been decided);
2118
2274
  \u2022 you are about to write or change a test (what this project expects a change to ship with, and how it asserts, is a convention, not a preference);
2119
2275
  \u2022 you are implementing something new, or two parts have to fit together;
2120
2276
  \u2022 the user asks why something is the way it is, or what is left to do;
2121
2277
  \u2022 you are about to commit, and need to know what the change was supposed to honour.
2122
- It ranks the pages by relevance and returns the matching passage, which a page title cannot tell you.
2278
+ It ranks the pages by relevance and returns the matching passage, which a page title cannot tell you. What it returns is a past record, not a live reading: a claim that something was fixed, passes, or works is what someone said then \u2014 check it against the code before you rely on it, and say so when the two disagree.
2123
2279
  CREDITING IS NOT OPTIONAL AND NOT A JUDGEMENT CALL. If you called this tool and anything it returned reached your reply \u2014 quoted, paraphrased, or merely confirming what you were about to say \u2014 open that part with a markdown blockquote, exactly: "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. A search that turned up nothing useful needs no mention at all \u2014 just carry on.
2124
2280
  - hindsight_list_knowledge_pages / hindsight_read_knowledge_page \u2014 BEFORE substantial work, list the pages and read the relevant ones to ground yourself in this repo's architecture, conventions, and past decisions instead of re-deriving them from the code; follow any [[page:<id>]] links you see.
2125
2281
  - hindsight_reflect(query) \u2014 when pages are too shallow and you need the WHY: deep reasoning over the repo's full memory for the past decision and exact values that explain a behavior or bug (slower \u2014 use deliberately, and credit results with a blockquote header "> \u{1F9E0} **From Hindsight memory** \u2014 <summary>").
@@ -2127,7 +2283,9 @@ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, a
2127
2283
  - hindsight_ingest_document(title, content) \u2014 save an external document or durable notes/findings you want remembered (not the current conversation \u2014 that is captured automatically at session end).`;
2128
2284
  var PAGES_FIRST_ON_GOALS = "- The user just set a NEW task or goal \u2192 search the knowledge pages FIRST with hindsight_search_knowledge_pages. No synthesis is injected automatically in this configuration; call hindsight_reflect only when those pages are too shallow and deeper reasoning is needed.\n";
2129
2285
  function toolGuide(opts) {
2130
- return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE;
2286
+ const extra = opts?.extra?.trim();
2287
+ return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE + (extra ? `
2288
+ ${extra}` : "");
2131
2289
  }
2132
2290
  function buildKnowledgePreamble(pages, opts) {
2133
2291
  const body = pages.length ? indexLine(pages) : EMPTY_STATE;
@@ -16673,6 +16831,7 @@ import { execFileSync as execFileSync3 } from "child_process";
16673
16831
  // src/core/git.ts
16674
16832
  import { execFileSync as execFileSync2 } from "child_process";
16675
16833
  import { resolve as resolve2 } from "path";
16834
+ var GITLOG_HEAD = "gitlog-head:";
16676
16835
  function git(repo, ...args) {
16677
16836
  return execFileSync2("git", ["-C", repo, ...args], {
16678
16837
  encoding: "utf8",
@@ -16694,6 +16853,7 @@ function gitHeadSha(dir) {
16694
16853
  }
16695
16854
  }
16696
16855
  function commitsSince(dir, sinceSha) {
16856
+ if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(sinceSha)) return null;
16697
16857
  try {
16698
16858
  const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
16699
16859
  return Number.isFinite(n) ? n : null;
@@ -16708,6 +16868,15 @@ function hasGitHistory(dir) {
16708
16868
  return false;
16709
16869
  }
16710
16870
  }
16871
+ async function gitLogIsCurrent(client, repo, head) {
16872
+ const canonical2 = `gitlog:${repoNameOf(repo)}`;
16873
+ if ((await client.listDocumentIds(`${GITLOG_HEAD}${head}`, "all_strict")).has(canonical2))
16874
+ return true;
16875
+ const tags = await client.documentTags?.(canonical2) ?? [];
16876
+ return tags.some(
16877
+ (tag) => tag.startsWith(GITLOG_HEAD) && commitsSince(repo, tag.slice(GITLOG_HEAD.length)) === 0
16878
+ );
16879
+ }
16711
16880
 
16712
16881
  // src/core/survey.ts
16713
16882
  import { spawn as realSpawn5 } from "child_process";
@@ -17070,19 +17239,7 @@ var NON_DESTRUCTIVE_WRITE_ANNOTATIONS = {
17070
17239
  idempotentHint: false,
17071
17240
  openWorldHint: false
17072
17241
  };
17073
- var CREDIT_REMINDER = 'Crediting is mandatory, not a judgement call: if anything these results contribute reaches your reply \u2014 quoted, paraphrased, or merely confirming what you were going to say \u2014 open that part with "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. If none of them bear on the turn, ignore them silently \u2014 an unhelpful search needs no mention.';
17074
- function shapePage(page) {
17075
- const p = page ?? {};
17076
- const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
17077
- return {
17078
- id: p.id,
17079
- name: p.name,
17080
- ...p.description ? { description: p.description } : {},
17081
- ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
17082
- ...p.timestamp ? { last_updated_at: p.timestamp } : {},
17083
- body
17084
- };
17085
- }
17242
+ var CREDIT_REMINDER = 'Crediting is mandatory, not a judgement call: if anything these results contribute reaches your reply \u2014 quoted, paraphrased, or merely confirming what you were going to say \u2014 open that part with "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. If none of them bear on the turn, ignore them silently \u2014 an unhelpful search needs no mention. These are past records: check a claim that something was fixed or works against the code before relying on it.';
17086
17243
  function ok(value) {
17087
17244
  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
17088
17245
  }
@@ -17100,6 +17257,8 @@ function guarded(fn) {
17100
17257
  };
17101
17258
  }
17102
17259
  function buildKnowledgeTools(client, bankId, opts = {}) {
17260
+ const extra = opts.toolGuideExtra?.trim();
17261
+ const crediting = extra ? `${CREDIT_REMINDER} ${extra}` : CREDIT_REMINDER;
17103
17262
  return [
17104
17263
  {
17105
17264
  name: "hindsight_sync_status",
@@ -17159,7 +17318,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17159
17318
  },
17160
17319
  {
17161
17320
  name: "hindsight_search_knowledge_pages",
17162
- description: "Search this repository's Hindsight knowledge pages for content relevant to a query \u2014 hybrid full-text + semantic search, server-side. Call this when the user's question may be answered by the project's accumulated knowledge (architecture, conventions, decisions, initiatives) rather than by reading code. Returns ranked pages with a relevance snippet; read a full page with hindsight_read_knowledge_page. " + CREDIT_REMINDER,
17321
+ description: "Search this repository's Hindsight knowledge pages for content relevant to a query \u2014 hybrid full-text + semantic search, server-side. Call this when the user's question may be answered by the project's accumulated knowledge (architecture, conventions, decisions, initiatives) rather than by reading code. Returns ranked pages with a relevance snippet; read a full page with hindsight_read_knowledge_page. " + crediting,
17163
17322
  inputSchema: { query: external_exports.string().describe("what to look for") },
17164
17323
  annotations: READ_ONLY_ANNOTATIONS,
17165
17324
  handler: async (args) => {
@@ -17169,9 +17328,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17169
17328
  pages: hits.map((h) => ({
17170
17329
  page: h.name,
17171
17330
  page_id: h.id,
17331
+ // The question the page answers — the same `description` the list and read tools
17332
+ // carry, so a hit says what the page is FOR, not just how it opens.
17333
+ ...h.source_query ? { description: h.source_query } : {},
17172
17334
  snippet: h.snippet
17173
17335
  })),
17174
- crediting: CREDIT_REMINDER
17336
+ crediting
17175
17337
  });
17176
17338
  } catch (e) {
17177
17339
  return err(e);
@@ -17190,7 +17352,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17190
17352
  description: "Read the full content of one knowledge page by its id (from hindsight_list_knowledge_pages). Call this whenever a listed page is relevant to what you're about to do \u2014 e.g. read Conventions before writing new code, Component map before changing a subsystem, or an initiative's page before continuing that feature. A page may contain [[page:<id>]] links to related pages; follow one by calling this tool again with that id. Prefer reading a page over re-deriving the same understanding from source.",
17191
17353
  inputSchema: { page_id: external_exports.string() },
17192
17354
  annotations: READ_ONLY_ANNOTATIONS,
17193
- handler: guarded(async ({ page_id }) => shapePage(await client.getPage(page_id)))
17355
+ handler: guarded(async ({ page_id }) => client.getPage(page_id))
17194
17356
  },
17195
17357
  {
17196
17358
  name: "hindsight_reflect",
@@ -17260,6 +17422,11 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17260
17422
  import { createHash as createHash4 } from "crypto";
17261
17423
  var PENDING_MAX_AGE_MS = 12 * 60 * 60 * 1e3;
17262
17424
  var PENDING_MAX_BYTES = 256 * 1024;
17425
+ var MAX_CURSOR_PATHS = 16;
17426
+ function advancePaths(seen, path) {
17427
+ if (!path) return seen;
17428
+ return [...(seen ?? []).filter((p) => p !== path), path].slice(-MAX_CURSOR_PATHS);
17429
+ }
17263
17430
  function pendingReplayable(cursor, now) {
17264
17431
  const pending = cursor.pending ?? [];
17265
17432
  if (!pending.length) return true;
@@ -17276,8 +17443,10 @@ function planRetain(turns, cursor, opts) {
17276
17443
  if (!opts.appendSupported || !cursor || cursor.dirty) return { mode: "replace" };
17277
17444
  if (!pendingReplayable(cursor, opts.now ?? Date.now())) return { mode: "replace" };
17278
17445
  if (cursor.bank !== opts.bank) return { mode: "replace" };
17279
- if (cursor.turns > turns.length) return { mode: "replace" };
17280
- if (fingerprintTurns(turns, cursor.turns) !== cursor.fingerprint) return { mode: "replace" };
17446
+ const seen = cursor.paths ?? [];
17447
+ const newFile = Boolean(opts.path && seen.length && !seen.includes(opts.path));
17448
+ const continues = cursor.turns <= turns.length && fingerprintTurns(turns, cursor.turns) === cursor.fingerprint;
17449
+ if (!continues) return newFile ? { mode: "append", fromTurn: 0 } : { mode: "replace" };
17281
17450
  if (cursor.turns === turns.length) return { mode: "skip" };
17282
17451
  return { mode: "append", fromTurn: cursor.turns };
17283
17452
  }
@@ -17319,7 +17488,7 @@ function renderSessionJsonl(refId, turns, baseTs) {
17319
17488
  }
17320
17489
  async function supportsAppend(client) {
17321
17490
  try {
17322
- return await client.supportsIdempotentRetain();
17491
+ return await client.supportsAppendRetain();
17323
17492
  } catch {
17324
17493
  return false;
17325
17494
  }
@@ -17353,6 +17522,7 @@ function serialize(cursors, sessionId, write2) {
17353
17522
  });
17354
17523
  return next;
17355
17524
  }
17525
+ var DEFAULT_RETAIN_CONTEXT = `conversation between the user and you (the coding agent): user turns are the user's words and decisions, assistant turns are yours. When an assistant turn says something is fixed, passes or works, record it as the agent's claim ("the agent reported X fixed"), not as an established fact.`;
17356
17526
  async function retainLiveSession(client, sessionId, turns, startTs, harness, opts = {}) {
17357
17527
  const cursors = opts.cursors;
17358
17528
  if (!cursors)
@@ -17364,20 +17534,36 @@ async function retainLiveSession(client, sessionId, turns, startTs, harness, opt
17364
17534
  harness,
17365
17535
  opts.stamp,
17366
17536
  void 0,
17367
- opts.retryUntil
17537
+ opts.retryUntil,
17538
+ opts.transcriptPath
17368
17539
  );
17369
17540
  return serialize(
17370
17541
  cursors,
17371
17542
  sessionId,
17372
- () => writeSession(client, sessionId, turns, startTs, harness, opts.stamp, cursors, opts.retryUntil)
17543
+ () => writeSession(
17544
+ client,
17545
+ sessionId,
17546
+ turns,
17547
+ startTs,
17548
+ harness,
17549
+ opts.stamp,
17550
+ cursors,
17551
+ opts.retryUntil,
17552
+ opts.transcriptPath
17553
+ )
17373
17554
  );
17374
17555
  }
17375
- async function writeSession(client, sessionId, turns, startTs, harness, stamp, cursors, retryUntil = Date.now() + DEFAULT_RETRY_WINDOW_MS) {
17556
+ async function writeSession(client, sessionId, turns, startTs, harness, stamp, cursors, retryUntil = Date.now() + DEFAULT_RETRY_WINDOW_MS, transcriptPath) {
17376
17557
  if (!turns.length) return;
17377
17558
  const refId = `conversation:${sessionId}`;
17378
17559
  const cursor = cursors?.read(sessionId);
17379
17560
  const appendSupported = Boolean(cursors) && (cursor?.appendSupported === true || await supportsAppend(client));
17380
- const plan = planRetain(turns, cursor, { appendSupported, bank: client.bank });
17561
+ const plan = planRetain(turns, cursor, {
17562
+ appendSupported,
17563
+ bank: client.bank,
17564
+ path: transcriptPath
17565
+ });
17566
+ const paths = plan.mode === "replace" ? transcriptPath ? [transcriptPath] : void 0 : advancePaths(cursor?.paths, transcriptPath);
17381
17567
  const outbox = plan.mode === "replace" ? [] : cursor?.pending ?? [];
17382
17568
  if (plan.mode === "skip" && !outbox.length) return;
17383
17569
  const opId = (mode, content) => uuidV5(`${client.bank}
@@ -17386,7 +17572,10 @@ ${mode}
17386
17572
  ${content}`);
17387
17573
  const submit = (content, operationId, append) => client.retain(
17388
17574
  content,
17389
- "coding agent session",
17575
+ // Configured context wins. Extraction reads this to decide whose claim a sentence is, so the
17576
+ // default names both speakers: the previous "coding agent session" said nothing about
17577
+ // authorship and let an assistant's proposal be recorded as the user's decision.
17578
+ stamp?.context ?? DEFAULT_RETAIN_CONTEXT,
17390
17579
  refId,
17391
17580
  // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
17392
17581
  // the documents list filters and draws its agent logo from, so a template cannot displace them.
@@ -17416,6 +17605,7 @@ ${content}`);
17416
17605
  turns: turns.length,
17417
17606
  fingerprint: fingerprintTurns(turns, turns.length),
17418
17607
  bank: client.bank,
17608
+ ...paths ? { paths } : {},
17419
17609
  ...appendSupported ? { appendSupported: true } : {}
17420
17610
  };
17421
17611
  const stillOurs = () => {
@@ -17532,7 +17722,8 @@ function resolversFor(ctx) {
17532
17722
  function buildRetainStamp(cfg, ctx) {
17533
17723
  const hasTags = Boolean(cfg.retainTags?.length);
17534
17724
  const hasMetadata = Boolean(cfg.retainMetadata && Object.keys(cfg.retainMetadata).length);
17535
- if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
17725
+ const hasContext = Boolean(cfg.retainContext?.trim());
17726
+ if (!hasTags && !hasMetadata && !hasContext) return { tags: [], metadata: {} };
17536
17727
  const base = resolversFor(ctx);
17537
17728
  const cache = /* @__PURE__ */ new Map();
17538
17729
  const resolvers = Object.fromEntries(
@@ -17556,19 +17747,22 @@ function buildRetainStamp(cfg, ctx) {
17556
17747
  for (const [key, value] of Object.entries(cfg.retainMetadata ?? {})) {
17557
17748
  metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
17558
17749
  }
17559
- return { tags, metadata };
17750
+ const context = hasContext ? applyTemplate(cfg.retainContext, resolvers, "retainContext").trim() || void 0 : void 0;
17751
+ return { tags, metadata, context };
17560
17752
  }
17561
17753
 
17562
17754
  // src/core/session-start.ts
17563
17755
  import { readFileSync as readFileSync8 } from "fs";
17564
17756
 
17565
17757
  // src/core/skill-sync.ts
17566
- import { cpSync, existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
17758
+ import { cpSync, existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
17567
17759
  import { homedir as homedir7 } from "os";
17568
- import { dirname as dirname8, join as join14 } from "path";
17760
+ import { dirname as dirname8, join as join15 } from "path";
17569
17761
  import { fileURLToPath as fileURLToPath5 } from "url";
17570
17762
 
17571
17763
  // src/core/skill-dirs.ts
17764
+ import { existsSync as existsSync5 } from "fs";
17765
+ import { join as join14 } from "path";
17572
17766
  var SKILL_DIRS = {
17573
17767
  "claude-code": [".claude", "skills"],
17574
17768
  // Codex and dsh share the agentskills-standard root; uninstalling either removes the one copy.
@@ -17581,6 +17775,8 @@ var SKILL_DIRS = {
17581
17775
  "cline-cli": [".cline", "data", "settings", "skills"],
17582
17776
  "qwen-code": [".qwen", "skills"],
17583
17777
  // Qwen's user-level skills root (Storage.getUserSkillsDirs)
17778
+ // Kimi Code's user-level skills root, alongside its config.toml and mcp.json.
17779
+ "kimi-code": [".kimi-code", "skills"],
17584
17780
  "factory-droid": [".factory", "skills"],
17585
17781
  // Droid's user-level skills root
17586
17782
  // ZCode scans TWO user roots by default (its resolveDefaultSkillRoots): `~/.zcode/skills` and the
@@ -17588,29 +17784,46 @@ var SKILL_DIRS = {
17588
17784
  // skill removal is by fixed directory name, so installing into the shared root would make
17589
17785
  // `uninstall zcode` take Codex's and dsh's copy with it.
17590
17786
  zcode: [".zcode", "skills"],
17787
+ // TraeCode's user-level skills root, resolved per edition by traecodeDotDir below — like ZCode's
17788
+ // its own, never the shared agentskills root other hosts install into.
17789
+ traecode: [".trae-cn", "skills"],
17591
17790
  // The pi family reads the shared ~/.agents/skills too, but writes its OWN root: skill removal is
17592
17791
  // by fixed directory name, so installing to the shared one would make `uninstall pi` take Codex's
17593
17792
  // and dsh's copy with it.
17594
17793
  pi: [".pi", "agent", "skills"],
17595
17794
  "prime-agent": [".prime", "agent", "skills"]
17596
17795
  };
17796
+ var TRAE_DOT_DIRS = [".trae-cn", ".trae"];
17797
+ var traecodeDotDirName = (home, exists = existsSync5) => {
17798
+ for (const dir of TRAE_DOT_DIRS) {
17799
+ if (exists(join14(home, dir))) return dir;
17800
+ }
17801
+ return ".trae-cn";
17802
+ };
17803
+ var resolveSkillDirs = (harness, home) => {
17804
+ const parts = SKILL_DIRS[harness];
17805
+ if (harness === "traecode" && parts) {
17806
+ return [traecodeDotDirName(home), ...parts.slice(1)];
17807
+ }
17808
+ return parts;
17809
+ };
17597
17810
 
17598
17811
  // src/core/skill-sync.ts
17599
17812
  function packagedSkillDir() {
17600
17813
  const here = dirname8(fileURLToPath5(import.meta.url));
17601
- const dist = join14(here, "..", "skill");
17602
- return existsSync5(join14(dist, "SKILL.md")) ? dist : join14(here, "..", "..", "skill");
17814
+ const dist = join15(here, "..", "skill");
17815
+ return existsSync6(join15(dist, "SKILL.md")) ? dist : join15(here, "..", "..", "skill");
17603
17816
  }
17604
17817
  function syncCompanionSkill(harness, opts = {}) {
17605
17818
  try {
17606
- const parts = SKILL_DIRS[harness];
17819
+ const parts = resolveSkillDirs(harness, opts.home ?? homedir7());
17607
17820
  if (!parts) return;
17608
17821
  const src = opts.srcDir ?? packagedSkillDir();
17609
- const srcMd = join14(src, "SKILL.md");
17610
- if (!existsSync5(srcMd)) return;
17611
- const dst = join14(opts.home ?? homedir7(), ...parts, "hindsight-coding-agent");
17612
- const dstMd = join14(dst, "SKILL.md");
17613
- const installed = existsSync5(dstMd);
17822
+ const srcMd = join15(src, "SKILL.md");
17823
+ if (!existsSync6(srcMd)) return;
17824
+ const dst = join15(opts.home ?? homedir7(), ...parts, "hindsight-coding-agent");
17825
+ const dstMd = join15(dst, "SKILL.md");
17826
+ const installed = existsSync6(dstMd);
17614
17827
  if (!installed && !opts.install) return;
17615
17828
  if (!installed || readFileSync5(srcMd, "utf8") !== readFileSync5(dstMd, "utf8")) {
17616
17829
  cpSync(src, dst, { recursive: true });
@@ -17634,15 +17847,15 @@ function brandWord() {
17634
17847
  }
17635
17848
 
17636
17849
  // src/core/legacy.ts
17637
- import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
17850
+ import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
17638
17851
  import { homedir as homedir8 } from "os";
17639
- import { join as join15, relative, isAbsolute as isAbsolute2 } from "path";
17852
+ import { join as join16, relative, isAbsolute as isAbsolute2 } from "path";
17640
17853
  var LEGACY_CLAUDE_PLUGIN = "hindsight-memory";
17641
- function detectLegacyClaudePlugin(cwd, claudeDir = join15(homedir8(), ".claude")) {
17642
- const registry3 = readJson(join15(claudeDir, "plugins", "installed_plugins.json"));
17854
+ function detectLegacyClaudePlugin(cwd, claudeDir = join16(homedir8(), ".claude")) {
17855
+ const registry3 = readJson(join16(claudeDir, "plugins", "installed_plugins.json"));
17643
17856
  const plugins = registry3?.plugins;
17644
17857
  if (!plugins || typeof plugins !== "object") return void 0;
17645
- const enabled = readJson(join15(claudeDir, "settings.json"))?.enabledPlugins;
17858
+ const enabled = readJson(join16(claudeDir, "settings.json"))?.enabledPlugins;
17646
17859
  for (const [key, raw] of Object.entries(plugins)) {
17647
17860
  if (key.split("@")[0] !== LEGACY_CLAUDE_PLUGIN) continue;
17648
17861
  if (enabled && enabled[key] === false) continue;
@@ -17673,9 +17886,9 @@ function legacyClaudePluginWarning(key) {
17673
17886
  // src/core/session-cache.ts
17674
17887
  import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync3, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
17675
17888
  import { tmpdir as tmpdir3 } from "os";
17676
- import { dirname as dirname9, join as join16 } from "path";
17889
+ import { dirname as dirname9, join as join17 } from "path";
17677
17890
  function sessionCacheFile(harness, sessionId) {
17678
- return join16(tmpdir3(), `hindsight-${harness}`, `${sessionId}.json`);
17891
+ return join17(tmpdir3(), `hindsight-${harness}`, `${sessionId}.json`);
17679
17892
  }
17680
17893
  function readSessionCache(cacheFile) {
17681
17894
  try {
@@ -17717,7 +17930,7 @@ async function gitSyncNote(args) {
17717
17930
  if (mode === "none" || cold) return void 0;
17718
17931
  const head = gitHeadSha(cwd);
17719
17932
  if (!head) return void 0;
17720
- const gitlogCurrent = await client.listDocumentIds(`gitlog-head:${head}`, "all_strict").then((s) => s.has(`gitlog:${repoNameOf(cwd)}`)).catch(() => void 0);
17933
+ const gitlogCurrent = await gitLogIsCurrent(client, cwd, head).catch(() => void 0);
17721
17934
  if (gitlogCurrent === void 0) return void 0;
17722
17935
  if (mode === "message") return gitlogCurrent ? "git in sync" : "catching up on new commits";
17723
17936
  const deepened = [...gitIds].filter((id) => id.startsWith("git:")).length;
@@ -17843,7 +18056,8 @@ async function buildSessionStartContext(args) {
17843
18056
  }
17844
18057
  }
17845
18058
  const additionalContext = buildKnowledgePreamble(pages, {
17846
- reflectOnNewGoals: cfg.autoInject !== "reflect"
18059
+ reflectOnNewGoals: cfg.autoInject !== "reflect",
18060
+ extra: cfg.toolGuideExtra
17847
18061
  });
17848
18062
  const deferInitialReflect = cold === true || pageListKnown && pages.length === 0;
17849
18063
  let gitNote;
@@ -17869,7 +18083,7 @@ ${legacyClaudePluginWarning(legacyPlugin)}`;
17869
18083
  }
17870
18084
 
17871
18085
  // src/core/hook.ts
17872
- import { existsSync as existsSync7, readFileSync as readFileSync10 } from "fs";
18086
+ import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
17873
18087
 
17874
18088
  // src/core/inject.ts
17875
18089
  function buildReflectQuery(prompt) {
@@ -17918,7 +18132,7 @@ If you VERIFY this memory is wrong or outdated (the code or facts contradict it)
17918
18132
  // src/core/turn-journal.ts
17919
18133
  import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync5, readFileSync as readFileSync9, statSync as statSync3 } from "fs";
17920
18134
  import { tmpdir as tmpdir4 } from "os";
17921
- import { dirname as dirname10, join as join17 } from "path";
18135
+ import { dirname as dirname10, join as join18 } from "path";
17922
18136
 
17923
18137
  // src/core/transcript-util.ts
17924
18138
  var MEMORY_TAG_RE = /<(hook_prompt|task-notification|system-reminder|hindsight_memory|hindsight_memories|hindsight_bank|relevant_memories|user_feedback|hindsight_knowledge|hindsight_knowledge_refresh)\b[\s\S]*?<\/\1>/g;
@@ -17959,7 +18173,6 @@ function actionLine(tool2, input) {
17959
18173
  var JOURNAL_MAX_BYTES = 8 * 1024 * 1024;
17960
18174
 
17961
18175
  // src/core/hook.ts
17962
- var HOOK_FALLBACK_BUDGET_MS = 7e3;
17963
18176
  var HOOK_INJECT_ATTEMPTS = 2;
17964
18177
  function resolveInjection(got, attempts) {
17965
18178
  if (got != null) return got;
@@ -17987,8 +18200,8 @@ async function injectRecall(harness, prompt, client, timeoutMs, event, lead) {
17987
18200
  return void 0;
17988
18201
  }
17989
18202
  }
17990
- async function reflectFallback(harness, prompt, client) {
17991
- const deadline = Date.now() + HOOK_FALLBACK_BUDGET_MS;
18203
+ async function reflectFallback(harness, prompt, client, timeoutMs) {
18204
+ const deadline = Date.now() + timeoutMs;
17992
18205
  const remaining = () => Math.max(deadline - Date.now(), 1);
17993
18206
  return await injectPages(harness, prompt, client, remaining(), "reflect_fallback_pages") ?? // Event name predates the `injectRecall` rename and is kept: it is a logged contract that
17994
18207
  // other tools read, so renaming it would silently break them.
@@ -18013,7 +18226,7 @@ async function buildHookOutput(args) {
18013
18226
  harness,
18014
18227
  prompt,
18015
18228
  client,
18016
- HOOK_FALLBACK_BUDGET_MS,
18229
+ cfg.injectTimeoutMs,
18017
18230
  "inject_pages",
18018
18231
  PAGE_INJECT_LEAD
18019
18232
  );
@@ -18026,7 +18239,7 @@ async function buildHookOutput(args) {
18026
18239
  harness,
18027
18240
  prompt,
18028
18241
  client,
18029
- HOOK_FALLBACK_BUDGET_MS,
18242
+ cfg.injectTimeoutMs,
18030
18243
  "inject_recall",
18031
18244
  RECALL_INJECT_LEAD
18032
18245
  );
@@ -18068,7 +18281,7 @@ async function buildHookOutput(args) {
18068
18281
  query: prompt.slice(0, 80)
18069
18282
  });
18070
18283
  if (e instanceof ReflectError && e.fallbackEligible) {
18071
- fallback = await reflectFallback(harness, prompt, client);
18284
+ fallback = await reflectFallback(harness, prompt, client, cfg.injectTimeoutMs);
18072
18285
  if (fallback) reflectAnswer = fallback;
18073
18286
  }
18074
18287
  }
@@ -18101,7 +18314,12 @@ async function buildHookOutput(args) {
18101
18314
  const blocks = [];
18102
18315
  if (reflectAnswer && reflectRanThisTurn) blocks.push(buildSystemInjection(reflectAnswer));
18103
18316
  if (cadence > 0 && turns % cadence === 0) {
18104
- blocks.push(buildRosterRefresh(pages, { reflectOnNewGoals: cfg.autoInject !== "reflect" }));
18317
+ blocks.push(
18318
+ buildRosterRefresh(pages, {
18319
+ reflectOnNewGoals: cfg.autoInject !== "reflect",
18320
+ extra: cfg.toolGuideExtra
18321
+ })
18322
+ );
18105
18323
  }
18106
18324
  const kept = blocks.filter(Boolean);
18107
18325
  let notice;
@@ -18170,6 +18388,7 @@ var RuntimeCore = class {
18170
18388
  pageTrigger: buildPageTrigger(this.cfg),
18171
18389
  reflectTimeoutMs: this.cfg.reflectToolTimeoutMs,
18172
18390
  reflectBudget: this.cfg.reflectBudget,
18391
+ toolGuideExtra: this.cfg.toolGuideExtra,
18173
18392
  stampFor: () => buildRetainStamp(this.cfg, {
18174
18393
  directory: this.projectDir,
18175
18394
  harness: this.harness,
@@ -18237,7 +18456,8 @@ var RuntimeCore = class {
18237
18456
  if (turns === 1) {
18238
18457
  blocks.push(
18239
18458
  buildKnowledgePreamble(output.pages, {
18240
- reflectOnNewGoals: this.cfg.autoInject !== "reflect"
18459
+ reflectOnNewGoals: this.cfg.autoInject !== "reflect",
18460
+ extra: this.cfg.toolGuideExtra
18241
18461
  })
18242
18462
  );
18243
18463
  }