@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/status.js CHANGED
@@ -250,13 +250,13 @@ function isWithin(directory, configured) {
250
250
  function mapLookup(map, directory) {
251
251
  const cwd = normalize(directory);
252
252
  let best;
253
- for (const [dir, bank] of Object.entries(map)) {
253
+ for (const [dir, value] of Object.entries(map)) {
254
254
  const p = configuredDir(dir);
255
255
  if (isWithin(cwd, p)) {
256
- if (!best || p.length > best.len) best = { len: p.length, bank };
256
+ if (!best || p.length > best.len) best = { len: p.length, value };
257
257
  }
258
258
  }
259
- return best?.bank;
259
+ return best?.value;
260
260
  }
261
261
  function lookupDirectories(config, directory, sessionRoot = "") {
262
262
  const directories = [normalize(directory)];
@@ -280,6 +280,10 @@ function isOptedIn(config, directory) {
280
280
  const pathMap = config.mapPathToBank;
281
281
  return Boolean(pathMap && directories.some((candidate) => mapLookup(pathMap, candidate)));
282
282
  }
283
+ function pathSection(config, paths, directory) {
284
+ if (!directory || !paths) return void 0;
285
+ return lookupDirectories(config, directory).map((candidate) => mapLookup(paths, candidate)).find((section) => section !== void 0);
286
+ }
283
287
  function mappedBank(config, directory, sessionRoot) {
284
288
  const pathMap = config.mapPathToBank;
285
289
  if (!directory || !pathMap) return void 0;
@@ -538,12 +542,17 @@ var CODING_BANK_TEMPLATE = {
538
542
  }
539
543
  };
540
544
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
545
+ var PLUGIN_GOVERNED_BANK_FIELDS = [
546
+ "retain_strategies",
547
+ "entity_labels",
548
+ "retain_extraction_mode"
549
+ ];
541
550
  function isSet(v) {
542
551
  if (v === null || v === void 0) return false;
543
552
  if (typeof v === "string") return v.trim() !== "";
544
553
  return true;
545
554
  }
546
- function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
555
+ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE, defaults = {}) {
547
556
  const current2 = overrides ?? {};
548
557
  const template = CODING_BANK_TEMPLATE.bank;
549
558
  const bank = {};
@@ -572,6 +581,10 @@ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
572
581
  const [knowledgeGroup] = template.entity_labels;
573
582
  if (!labels.some((g) => g?.key === knowledgeGroup.key))
574
583
  bank.entity_labels = [...labels, knowledgeGroup];
584
+ for (const [key, value] of Object.entries(defaults)) {
585
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key) || !isSet(value) || isSet(current2[key])) continue;
586
+ bank[key] = value;
587
+ }
575
588
  return Object.keys(bank).length > 0 ? { version: "1", bank } : void 0;
576
589
  }
577
590
 
@@ -675,6 +688,18 @@ var DEFAULT_RECALL_OPTIONS = {
675
688
  var POLL_CYCLE_MS = 5e3;
676
689
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
677
690
  var RETRY_AFTER_CEILING_MS = 60 * 1e3;
691
+ function shapePage(page) {
692
+ const p = page ?? {};
693
+ const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
694
+ return {
695
+ id: p.id,
696
+ name: p.name,
697
+ ...p.description ? { description: p.description } : {},
698
+ ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
699
+ ...p.timestamp ? { last_updated_at: p.timestamp } : {},
700
+ body
701
+ };
702
+ }
678
703
  var HindsightClient = class {
679
704
  apiUrl;
680
705
  /** The credential the NEXT request will sign with — NOT the one the config file holds. The two
@@ -712,7 +737,10 @@ var HindsightClient = class {
712
737
  return this.token;
713
738
  }
714
739
  headers() {
715
- const h = { "Content-Type": "application/json" };
740
+ const h = {
741
+ "Content-Type": "application/json",
742
+ "Accept-Encoding": "identity"
743
+ };
716
744
  if (this.token) h["Authorization"] = `Bearer ${this.token}`;
717
745
  return h;
718
746
  }
@@ -820,6 +848,23 @@ var HindsightClient = class {
820
848
  return false;
821
849
  }
822
850
  }
851
+ /**
852
+ * Whether a session write-back may use `update_mode="append"`: the server must dedupe by
853
+ * `operation_id` AND the bank must keep document text, or the server rejects the append in the
854
+ * background (#4613). Only an explicit `store_document_text: false` answers "no" — an unreachable
855
+ * or unparseable config assumes the default (stored), so a flaky probe never downgrades appends.
856
+ */
857
+ async supportsAppendRetain() {
858
+ if (!await this.supportsIdempotentRetain()) return false;
859
+ try {
860
+ const r = await this.req("GET", this.bankUrl("/config"));
861
+ if (!r.ok) return true;
862
+ const j = await r.json();
863
+ return j.config?.store_document_text !== false;
864
+ } catch {
865
+ return true;
866
+ }
867
+ }
823
868
  /**
824
869
  * Every document_id currently in the bank under a strategy tag (e.g. `source:git`), paginated into a
825
870
  * Set. Powers the incremental git-sync's "what's already ingested?" check — since git commits are stored
@@ -845,6 +890,24 @@ var HindsightClient = class {
845
890
  }
846
891
  return ids;
847
892
  }
893
+ /**
894
+ * The tags on one document, or undefined when the bank holds none with that id. Read from the
895
+ * document LISTING narrowed by `q` (a substring match on the id, so the exact id is picked out of
896
+ * the page) rather than GET /documents/{id}, which also sends the document's full text: the
897
+ * caller, the git-log freshness check on SessionStart, reads a ~100k-character document for one tag.
898
+ */
899
+ async documentTags(documentId) {
900
+ const limit = 100;
901
+ for (let offset = 0; ; offset += limit) {
902
+ const q = `?q=${encodeURIComponent(documentId)}&limit=${limit}&offset=${offset}`;
903
+ const r = await this.req("GET", this.bankUrl(`/documents${q}`));
904
+ const j = await r.json();
905
+ const items = j.items ?? [];
906
+ const hit = items.find((it) => it.id === documentId);
907
+ if (hit) return hit.tags ?? [];
908
+ if (items.length < limit || offset + limit >= (j.total ?? 0)) return void 0;
909
+ }
910
+ }
848
911
  /** Configure the bank: POST the coding bank manifest to /import (missions, retain strategies,
849
912
  * entity labels), then seed knowledge pages when the server supports them. Both halves are
850
913
  * idempotent and ADDITIVE — nothing the bank already says is overwritten (#3927), bar the
@@ -866,7 +929,8 @@ var HindsightClient = class {
866
929
  } else {
867
930
  const manifest = codingBankManifest(
868
931
  opts.reset ? void 0 : await this.readBankOverrides(),
869
- opts.extractionMode
932
+ opts.extractionMode,
933
+ opts.defaults
870
934
  );
871
935
  if (!manifest) {
872
936
  this.log(`[bank] ${this.bank} already carries the coding structure \u2014 nothing to apply`);
@@ -1072,8 +1136,8 @@ var HindsightClient = class {
1072
1136
  return { items };
1073
1137
  }
1074
1138
  /**
1075
- * Read one knowledge page's synthesized content by knowledge-base id, as an OKF document
1076
- * (YAML frontmatter + markdown body). The endpoint omits the internal reflect trace that built
1139
+ * Read one knowledge page's synthesized content by knowledge-base id, shaped by `shapePage` so
1140
+ * the body arrives once. The endpoint omits the internal reflect trace that built
1077
1141
  * the page — that is 70-95% of the raw bytes and can blow past an MCP host's per-tool-result
1078
1142
  * token cap.
1079
1143
  */
@@ -1084,7 +1148,7 @@ var HindsightClient = class {
1084
1148
  this.bankUrl(`/knowledge-base/pages/${encodeURIComponent(pageId)}`)
1085
1149
  );
1086
1150
  if (r.status === 404) throw new Error(`knowledge page not found: ${pageId}`);
1087
- return await r.json();
1151
+ return shapePage(await r.json());
1088
1152
  }
1089
1153
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
1090
1154
  * Returns page-level hits with a relevance snippet — the real search behind
@@ -1105,6 +1169,7 @@ var HindsightClient = class {
1105
1169
  return (j.results ?? []).map((x) => ({
1106
1170
  id: x.id,
1107
1171
  name: x.name,
1172
+ ...x.source_query ? { source_query: x.source_query } : {},
1108
1173
  snippet: x.snippet ?? "",
1109
1174
  score: x.score ?? 0
1110
1175
  }));
@@ -1375,6 +1440,7 @@ function resolveCustomPages(raw) {
1375
1440
  }
1376
1441
  var DEFAULT_REFLECT_TIMEOUT_MS = 2e4;
1377
1442
  var DEFAULT_REFLECT_TOOL_TIMEOUT_MS = 33e4;
1443
+ var DEFAULT_INJECT_TIMEOUT_MS = 7e3;
1378
1444
  var REFLECT_BUDGETS = ["low", "mid", "high"];
1379
1445
  function resolveReflectBudget(raw) {
1380
1446
  const value = raw.reflectBudget;
@@ -1401,6 +1467,22 @@ function resolveObservationScopes(raw) {
1401
1467
  }
1402
1468
  return DEFAULT_OBSERVATION_SCOPES;
1403
1469
  }
1470
+ function resolveDefaultBankConfig(raw) {
1471
+ const value = raw;
1472
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
1473
+ const out = {};
1474
+ for (const [key, v] of Object.entries(value)) {
1475
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key)) {
1476
+ log.warn(
1477
+ "config",
1478
+ `ignoring defaultBankConfig.${key} \u2014 the plugin manages this field itself` + (key === "retain_extraction_mode" ? " (set retainExtractionMode instead)" : "")
1479
+ );
1480
+ continue;
1481
+ }
1482
+ out[key] = v;
1483
+ }
1484
+ return out;
1485
+ }
1404
1486
  var AUTO_INJECT_MODES = ["reflect", "pages", "recall", "none"];
1405
1487
  function resolveAutoInject(raw) {
1406
1488
  if (raw.autoReflect !== void 0) {
@@ -1440,18 +1522,21 @@ function resolveConfig(raw = {}) {
1440
1522
  // write sessions back by default, every harness
1441
1523
  manageBankConfig: raw.manageBankConfig ?? true,
1442
1524
  retainExtractionMode: RETAIN_EXTRACTION_MODES.includes(raw.retainExtractionMode) ? raw.retainExtractionMode : DEFAULT_RETAIN_EXTRACTION_MODE,
1525
+ defaultBankConfig: resolveDefaultBankConfig(raw.defaultBankConfig),
1443
1526
  maxParallelRetains: raw.maxParallelRetains || 10,
1444
1527
  reflectTimeoutMs: raw.reflectTimeoutMs || DEFAULT_REFLECT_TIMEOUT_MS,
1445
1528
  // Inherit an explicitly-raised reflectTimeoutMs (that is what users reaching for a longer
1446
1529
  // reflect already set), but never let it LOWER the tool below the default — a short window is
1447
1530
  // set to bound the automatic hook, not to cut off a call the agent is waiting on.
1448
1531
  reflectToolTimeoutMs: raw.reflectToolTimeoutMs || Math.max(raw.reflectTimeoutMs || 0, DEFAULT_REFLECT_TOOL_TIMEOUT_MS),
1532
+ injectTimeoutMs: raw.injectTimeoutMs || DEFAULT_INJECT_TIMEOUT_MS,
1449
1533
  reflectBudget: resolveReflectBudget(raw),
1450
1534
  autoInject: resolveAutoInject(raw),
1451
1535
  pageSearchLimit: raw.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT,
1452
1536
  // Same shape as retainMetadata: an object, or nothing. An array would spread into numeric
1453
1537
  // keys and reach the API as garbage, so it is rejected like any other non-object.
1454
1538
  recallOptions: raw.recallOptions && typeof raw.recallOptions === "object" && !Array.isArray(raw.recallOptions) ? { ...raw.recallOptions } : {},
1539
+ toolGuideExtra: typeof raw.toolGuideExtra === "string" && raw.toolGuideExtra.trim() ? raw.toolGuideExtra : void 0,
1455
1540
  // Every turn, not every tenth. The guide is what tells the agent WHEN to reach for memory, and
1456
1541
  // at a cadence of 10 a normal session is told once, on turn 1, and never again. Measured over
1457
1542
  // 40 real Claude Code turns, moving this from 10 to 1 took searches from 15% of turns to 32.5%
@@ -1471,11 +1556,15 @@ function resolveConfig(raw = {}) {
1471
1556
  // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
1472
1557
  // nested object cannot reach the API as a tag and fail the whole retain.
1473
1558
  retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
1559
+ // Undefined, not "", when unset or blank: the retain call distinguishes "not configured" (use
1560
+ // the built-in default) from a configured value, and an empty context would strip the default.
1561
+ retainContext: typeof raw.retainContext === "string" && raw.retainContext.trim() !== "" ? raw.retainContext : void 0,
1474
1562
  retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
1475
1563
  Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
1476
1564
  ) : {},
1477
1565
  observationScopes: resolveObservationScopes(raw.observationScopes),
1478
1566
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
1567
+ paths: raw.paths && typeof raw.paths === "object" ? raw.paths : {},
1479
1568
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info",
1480
1569
  autoUpdate: raw.autoUpdate ?? true
1481
1570
  };
@@ -1492,7 +1581,12 @@ function readRaw(path) {
1492
1581
  }
1493
1582
  function mergeRaw(a, b) {
1494
1583
  const { harnesses: _drop, ...flat } = b;
1495
- return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
1584
+ return {
1585
+ ...a,
1586
+ ...flat,
1587
+ banks: { ...a.banks ?? {}, ...b.banks ?? {} },
1588
+ paths: { ...a.paths ?? {}, ...b.paths ?? {} }
1589
+ };
1496
1590
  }
1497
1591
  function applyLayer(raw, layer, harness) {
1498
1592
  let out = mergeRaw(raw, layer);
@@ -1523,9 +1617,11 @@ var ENV_KEYS = {
1523
1617
  maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
1524
1618
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
1525
1619
  reflectToolTimeoutMs: "HINDSIGHT_REFLECT_TOOL_TIMEOUT_MS",
1620
+ injectTimeoutMs: "HINDSIGHT_INJECT_TIMEOUT_MS",
1526
1621
  reflectBudget: "HINDSIGHT_REFLECT_BUDGET",
1527
1622
  autoInject: "HINDSIGHT_AUTO_INJECT",
1528
1623
  pageSearchLimit: "HINDSIGHT_PAGE_SEARCH_LIMIT",
1624
+ toolGuideExtra: "HINDSIGHT_TOOL_GUIDE_EXTRA",
1529
1625
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
1530
1626
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
1531
1627
  pageTriggerType: "HINDSIGHT_PAGE_TRIGGER_TYPE",
@@ -1567,6 +1663,7 @@ var ENV_NUMBERS = /* @__PURE__ */ new Set([
1567
1663
  "maxParallelRetains",
1568
1664
  "reflectTimeoutMs",
1569
1665
  "reflectToolTimeoutMs",
1666
+ "injectTimeoutMs",
1570
1667
  "pageSearchLimit",
1571
1668
  "pageRefreshEveryTurns",
1572
1669
  "seedLimit",
@@ -1615,15 +1712,25 @@ var BANK_OVERRIDE_EXCLUDED = [
1615
1712
  function applyBankConfig(cfg2, resolvedId, directory) {
1616
1713
  if (directory !== void 0 && !isOptedIn(cfg2, directory))
1617
1714
  return { cfg: { ...cfg2, disabled: true }, bankId: resolvedId };
1715
+ const byPath = directory === void 0 ? void 0 : pathSection(cfg2, cfg2.paths, directory);
1716
+ if (byPath) {
1717
+ const { bank: _rename, ...rest } = overrideFields(byPath);
1718
+ cfg2 = { ...cfg2, ...resolvePartial(cfg2, rest) };
1719
+ }
1618
1720
  const section = cfg2.banks[resolvedId];
1619
1721
  if (!section) return { cfg: cfg2, bankId: resolvedId };
1620
- const safe = { ...section };
1621
- for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1622
- delete safe.banks;
1722
+ const safe = overrideFields(section);
1623
1723
  const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
1624
1724
  delete safe.bank;
1625
1725
  return { cfg: { ...cfg2, ...resolvePartial(cfg2, safe) }, bankId };
1626
1726
  }
1727
+ function overrideFields(section) {
1728
+ const safe = { ...section };
1729
+ for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1730
+ delete safe.banks;
1731
+ delete safe.paths;
1732
+ return safe;
1733
+ }
1627
1734
  function resolvePartial(cfg2, patch) {
1628
1735
  const full = resolveConfig(patch);
1629
1736
  const out = {};
@@ -1632,6 +1739,16 @@ function resolvePartial(cfg2, patch) {
1632
1739
  out[key] = full[key];
1633
1740
  }
1634
1741
  if ("autoReflect" in patch && !("autoInject" in patch)) out.autoInject = full.autoInject;
1742
+ if ("serverMode" in patch || "apiUrl" in patch || "apiPort" in patch) {
1743
+ const conn = resolveConfig({
1744
+ serverMode: patch.serverMode ?? cfg2.serverMode,
1745
+ apiPort: patch.apiPort ?? cfg2.apiPort,
1746
+ apiUrl: patch.apiUrl ?? (cfg2.serverMode === "daemon" ? void 0 : cfg2.apiUrl)
1747
+ });
1748
+ out.serverMode = conn.serverMode;
1749
+ out.apiUrl = conn.apiUrl;
1750
+ out.apiPort = conn.apiPort;
1751
+ }
1635
1752
  return out;
1636
1753
  }
1637
1754
 
@@ -1655,6 +1772,7 @@ function repoNameOf(repo) {
1655
1772
  return projectNameOf(resolve2(repo));
1656
1773
  }
1657
1774
  function commitsSince(dir, sinceSha) {
1775
+ if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(sinceSha)) return null;
1658
1776
  try {
1659
1777
  const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
1660
1778
  return Number.isFinite(n) ? n : null;
@@ -1784,7 +1902,7 @@ if (!BANK) {
1784
1902
  console.error("usage: node status.js --repo <path> [--bank <id>] [--api-url U]");
1785
1903
  process.exit(1);
1786
1904
  }
1787
- var resolved0 = BANK ? applyBankConfig(cfg0, BANK) : { cfg: cfg0, bankId: BANK };
1905
+ var resolved0 = BANK ? applyBankConfig(cfg0, BANK, REPO) : { cfg: cfg0, bankId: BANK };
1788
1906
  var cfg = resolved0.cfg;
1789
1907
  var FINAL_BANK = resolved0.bankId ?? BANK;
1790
1908
  var client = new HindsightClient({