@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
@@ -31539,13 +31539,13 @@ function isWithin(directory, configured) {
31539
31539
  function mapLookup(map2, directory) {
31540
31540
  const cwd = normalize(directory);
31541
31541
  let best;
31542
- for (const [dir, bank] of Object.entries(map2)) {
31542
+ for (const [dir, value] of Object.entries(map2)) {
31543
31543
  const p = configuredDir(dir);
31544
31544
  if (isWithin(cwd, p)) {
31545
- if (!best || p.length > best.len) best = { len: p.length, bank };
31545
+ if (!best || p.length > best.len) best = { len: p.length, value };
31546
31546
  }
31547
31547
  }
31548
- return best?.bank;
31548
+ return best?.value;
31549
31549
  }
31550
31550
  function lookupDirectories(config2, directory, sessionRoot = "") {
31551
31551
  const directories = [normalize(directory)];
@@ -31569,6 +31569,10 @@ function isOptedIn(config2, directory) {
31569
31569
  const pathMap = config2.mapPathToBank;
31570
31570
  return Boolean(pathMap && directories.some((candidate) => mapLookup(pathMap, candidate)));
31571
31571
  }
31572
+ function pathSection(config2, paths, directory) {
31573
+ if (!directory || !paths) return void 0;
31574
+ return lookupDirectories(config2, directory).map((candidate) => mapLookup(paths, candidate)).find((section) => section !== void 0);
31575
+ }
31572
31576
  function mappedBank(config2, directory, sessionRoot) {
31573
31577
  const pathMap = config2.mapPathToBank;
31574
31578
  if (!directory || !pathMap) return void 0;
@@ -31816,12 +31820,17 @@ var CODING_BANK_TEMPLATE = {
31816
31820
  }
31817
31821
  };
31818
31822
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
31823
+ var PLUGIN_GOVERNED_BANK_FIELDS = [
31824
+ "retain_strategies",
31825
+ "entity_labels",
31826
+ "retain_extraction_mode"
31827
+ ];
31819
31828
  function isSet(v) {
31820
31829
  if (v === null || v === void 0) return false;
31821
31830
  if (typeof v === "string") return v.trim() !== "";
31822
31831
  return true;
31823
31832
  }
31824
- function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
31833
+ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE, defaults = {}) {
31825
31834
  const current2 = overrides ?? {};
31826
31835
  const template = CODING_BANK_TEMPLATE.bank;
31827
31836
  const bank = {};
@@ -31850,6 +31859,10 @@ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
31850
31859
  const [knowledgeGroup] = template.entity_labels;
31851
31860
  if (!labels.some((g) => g?.key === knowledgeGroup.key))
31852
31861
  bank.entity_labels = [...labels, knowledgeGroup];
31862
+ for (const [key, value] of Object.entries(defaults)) {
31863
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key) || !isSet(value) || isSet(current2[key])) continue;
31864
+ bank[key] = value;
31865
+ }
31853
31866
  return Object.keys(bank).length > 0 ? { version: "1", bank } : void 0;
31854
31867
  }
31855
31868
 
@@ -31953,6 +31966,18 @@ var DEFAULT_RECALL_OPTIONS = {
31953
31966
  var POLL_CYCLE_MS = 5e3;
31954
31967
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
31955
31968
  var RETRY_AFTER_CEILING_MS = 60 * 1e3;
31969
+ function shapePage(page) {
31970
+ const p = page ?? {};
31971
+ const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
31972
+ return {
31973
+ id: p.id,
31974
+ name: p.name,
31975
+ ...p.description ? { description: p.description } : {},
31976
+ ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
31977
+ ...p.timestamp ? { last_updated_at: p.timestamp } : {},
31978
+ body
31979
+ };
31980
+ }
31956
31981
  var HindsightClient = class {
31957
31982
  apiUrl;
31958
31983
  /** The credential the NEXT request will sign with — NOT the one the config file holds. The two
@@ -31990,7 +32015,10 @@ var HindsightClient = class {
31990
32015
  return this.token;
31991
32016
  }
31992
32017
  headers() {
31993
- const h = { "Content-Type": "application/json" };
32018
+ const h = {
32019
+ "Content-Type": "application/json",
32020
+ "Accept-Encoding": "identity"
32021
+ };
31994
32022
  if (this.token) h["Authorization"] = `Bearer ${this.token}`;
31995
32023
  return h;
31996
32024
  }
@@ -32098,6 +32126,23 @@ var HindsightClient = class {
32098
32126
  return false;
32099
32127
  }
32100
32128
  }
32129
+ /**
32130
+ * Whether a session write-back may use `update_mode="append"`: the server must dedupe by
32131
+ * `operation_id` AND the bank must keep document text, or the server rejects the append in the
32132
+ * background (#4613). Only an explicit `store_document_text: false` answers "no" — an unreachable
32133
+ * or unparseable config assumes the default (stored), so a flaky probe never downgrades appends.
32134
+ */
32135
+ async supportsAppendRetain() {
32136
+ if (!await this.supportsIdempotentRetain()) return false;
32137
+ try {
32138
+ const r = await this.req("GET", this.bankUrl("/config"));
32139
+ if (!r.ok) return true;
32140
+ const j = await r.json();
32141
+ return j.config?.store_document_text !== false;
32142
+ } catch {
32143
+ return true;
32144
+ }
32145
+ }
32101
32146
  /**
32102
32147
  * Every document_id currently in the bank under a strategy tag (e.g. `source:git`), paginated into a
32103
32148
  * Set. Powers the incremental git-sync's "what's already ingested?" check — since git commits are stored
@@ -32123,6 +32168,24 @@ var HindsightClient = class {
32123
32168
  }
32124
32169
  return ids;
32125
32170
  }
32171
+ /**
32172
+ * The tags on one document, or undefined when the bank holds none with that id. Read from the
32173
+ * document LISTING narrowed by `q` (a substring match on the id, so the exact id is picked out of
32174
+ * the page) rather than GET /documents/{id}, which also sends the document's full text: the
32175
+ * caller, the git-log freshness check on SessionStart, reads a ~100k-character document for one tag.
32176
+ */
32177
+ async documentTags(documentId) {
32178
+ const limit = 100;
32179
+ for (let offset = 0; ; offset += limit) {
32180
+ const q = `?q=${encodeURIComponent(documentId)}&limit=${limit}&offset=${offset}`;
32181
+ const r = await this.req("GET", this.bankUrl(`/documents${q}`));
32182
+ const j = await r.json();
32183
+ const items = j.items ?? [];
32184
+ const hit = items.find((it) => it.id === documentId);
32185
+ if (hit) return hit.tags ?? [];
32186
+ if (items.length < limit || offset + limit >= (j.total ?? 0)) return void 0;
32187
+ }
32188
+ }
32126
32189
  /** Configure the bank: POST the coding bank manifest to /import (missions, retain strategies,
32127
32190
  * entity labels), then seed knowledge pages when the server supports them. Both halves are
32128
32191
  * idempotent and ADDITIVE — nothing the bank already says is overwritten (#3927), bar the
@@ -32144,7 +32207,8 @@ var HindsightClient = class {
32144
32207
  } else {
32145
32208
  const manifest = codingBankManifest(
32146
32209
  opts.reset ? void 0 : await this.readBankOverrides(),
32147
- opts.extractionMode
32210
+ opts.extractionMode,
32211
+ opts.defaults
32148
32212
  );
32149
32213
  if (!manifest) {
32150
32214
  this.log(`[bank] ${this.bank} already carries the coding structure \u2014 nothing to apply`);
@@ -32350,8 +32414,8 @@ var HindsightClient = class {
32350
32414
  return { items };
32351
32415
  }
32352
32416
  /**
32353
- * Read one knowledge page's synthesized content by knowledge-base id, as an OKF document
32354
- * (YAML frontmatter + markdown body). The endpoint omits the internal reflect trace that built
32417
+ * Read one knowledge page's synthesized content by knowledge-base id, shaped by `shapePage` so
32418
+ * the body arrives once. The endpoint omits the internal reflect trace that built
32355
32419
  * the page — that is 70-95% of the raw bytes and can blow past an MCP host's per-tool-result
32356
32420
  * token cap.
32357
32421
  */
@@ -32362,7 +32426,7 @@ var HindsightClient = class {
32362
32426
  this.bankUrl(`/knowledge-base/pages/${encodeURIComponent(pageId)}`)
32363
32427
  );
32364
32428
  if (r.status === 404) throw new Error(`knowledge page not found: ${pageId}`);
32365
- return await r.json();
32429
+ return shapePage(await r.json());
32366
32430
  }
32367
32431
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
32368
32432
  * Returns page-level hits with a relevance snippet — the real search behind
@@ -32383,6 +32447,7 @@ var HindsightClient = class {
32383
32447
  return (j.results ?? []).map((x) => ({
32384
32448
  id: x.id,
32385
32449
  name: x.name,
32450
+ ...x.source_query ? { source_query: x.source_query } : {},
32386
32451
  snippet: x.snippet ?? "",
32387
32452
  score: x.score ?? 0
32388
32453
  }));
@@ -32653,6 +32718,7 @@ function resolveCustomPages(raw) {
32653
32718
  }
32654
32719
  var DEFAULT_REFLECT_TIMEOUT_MS = 2e4;
32655
32720
  var DEFAULT_REFLECT_TOOL_TIMEOUT_MS = 33e4;
32721
+ var DEFAULT_INJECT_TIMEOUT_MS = 7e3;
32656
32722
  var REFLECT_BUDGETS = ["low", "mid", "high"];
32657
32723
  function resolveReflectBudget(raw) {
32658
32724
  const value = raw.reflectBudget;
@@ -32679,6 +32745,22 @@ function resolveObservationScopes(raw) {
32679
32745
  }
32680
32746
  return DEFAULT_OBSERVATION_SCOPES;
32681
32747
  }
32748
+ function resolveDefaultBankConfig(raw) {
32749
+ const value = raw;
32750
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
32751
+ const out = {};
32752
+ for (const [key, v] of Object.entries(value)) {
32753
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key)) {
32754
+ log.warn(
32755
+ "config",
32756
+ `ignoring defaultBankConfig.${key} \u2014 the plugin manages this field itself` + (key === "retain_extraction_mode" ? " (set retainExtractionMode instead)" : "")
32757
+ );
32758
+ continue;
32759
+ }
32760
+ out[key] = v;
32761
+ }
32762
+ return out;
32763
+ }
32682
32764
  var AUTO_INJECT_MODES = ["reflect", "pages", "recall", "none"];
32683
32765
  function resolveAutoInject(raw) {
32684
32766
  if (raw.autoReflect !== void 0) {
@@ -32718,18 +32800,21 @@ function resolveConfig(raw = {}) {
32718
32800
  // write sessions back by default, every harness
32719
32801
  manageBankConfig: raw.manageBankConfig ?? true,
32720
32802
  retainExtractionMode: RETAIN_EXTRACTION_MODES.includes(raw.retainExtractionMode) ? raw.retainExtractionMode : DEFAULT_RETAIN_EXTRACTION_MODE,
32803
+ defaultBankConfig: resolveDefaultBankConfig(raw.defaultBankConfig),
32721
32804
  maxParallelRetains: raw.maxParallelRetains || 10,
32722
32805
  reflectTimeoutMs: raw.reflectTimeoutMs || DEFAULT_REFLECT_TIMEOUT_MS,
32723
32806
  // Inherit an explicitly-raised reflectTimeoutMs (that is what users reaching for a longer
32724
32807
  // reflect already set), but never let it LOWER the tool below the default — a short window is
32725
32808
  // set to bound the automatic hook, not to cut off a call the agent is waiting on.
32726
32809
  reflectToolTimeoutMs: raw.reflectToolTimeoutMs || Math.max(raw.reflectTimeoutMs || 0, DEFAULT_REFLECT_TOOL_TIMEOUT_MS),
32810
+ injectTimeoutMs: raw.injectTimeoutMs || DEFAULT_INJECT_TIMEOUT_MS,
32727
32811
  reflectBudget: resolveReflectBudget(raw),
32728
32812
  autoInject: resolveAutoInject(raw),
32729
32813
  pageSearchLimit: raw.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT,
32730
32814
  // Same shape as retainMetadata: an object, or nothing. An array would spread into numeric
32731
32815
  // keys and reach the API as garbage, so it is rejected like any other non-object.
32732
32816
  recallOptions: raw.recallOptions && typeof raw.recallOptions === "object" && !Array.isArray(raw.recallOptions) ? { ...raw.recallOptions } : {},
32817
+ toolGuideExtra: typeof raw.toolGuideExtra === "string" && raw.toolGuideExtra.trim() ? raw.toolGuideExtra : void 0,
32733
32818
  // Every turn, not every tenth. The guide is what tells the agent WHEN to reach for memory, and
32734
32819
  // at a cadence of 10 a normal session is told once, on turn 1, and never again. Measured over
32735
32820
  // 40 real Claude Code turns, moving this from 10 to 1 took searches from 15% of turns to 32.5%
@@ -32749,11 +32834,15 @@ function resolveConfig(raw = {}) {
32749
32834
  // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
32750
32835
  // nested object cannot reach the API as a tag and fail the whole retain.
32751
32836
  retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
32837
+ // Undefined, not "", when unset or blank: the retain call distinguishes "not configured" (use
32838
+ // the built-in default) from a configured value, and an empty context would strip the default.
32839
+ retainContext: typeof raw.retainContext === "string" && raw.retainContext.trim() !== "" ? raw.retainContext : void 0,
32752
32840
  retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
32753
32841
  Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
32754
32842
  ) : {},
32755
32843
  observationScopes: resolveObservationScopes(raw.observationScopes),
32756
32844
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
32845
+ paths: raw.paths && typeof raw.paths === "object" ? raw.paths : {},
32757
32846
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info",
32758
32847
  autoUpdate: raw.autoUpdate ?? true
32759
32848
  };
@@ -32770,7 +32859,12 @@ function readRaw(path) {
32770
32859
  }
32771
32860
  function mergeRaw(a, b) {
32772
32861
  const { harnesses: _drop, ...flat } = b;
32773
- return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
32862
+ return {
32863
+ ...a,
32864
+ ...flat,
32865
+ banks: { ...a.banks ?? {}, ...b.banks ?? {} },
32866
+ paths: { ...a.paths ?? {}, ...b.paths ?? {} }
32867
+ };
32774
32868
  }
32775
32869
  function applyLayer(raw, layer, harness) {
32776
32870
  let out = mergeRaw(raw, layer);
@@ -32801,9 +32895,11 @@ var ENV_KEYS = {
32801
32895
  maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
32802
32896
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
32803
32897
  reflectToolTimeoutMs: "HINDSIGHT_REFLECT_TOOL_TIMEOUT_MS",
32898
+ injectTimeoutMs: "HINDSIGHT_INJECT_TIMEOUT_MS",
32804
32899
  reflectBudget: "HINDSIGHT_REFLECT_BUDGET",
32805
32900
  autoInject: "HINDSIGHT_AUTO_INJECT",
32806
32901
  pageSearchLimit: "HINDSIGHT_PAGE_SEARCH_LIMIT",
32902
+ toolGuideExtra: "HINDSIGHT_TOOL_GUIDE_EXTRA",
32807
32903
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
32808
32904
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
32809
32905
  pageTriggerType: "HINDSIGHT_PAGE_TRIGGER_TYPE",
@@ -32845,6 +32941,7 @@ var ENV_NUMBERS = /* @__PURE__ */ new Set([
32845
32941
  "maxParallelRetains",
32846
32942
  "reflectTimeoutMs",
32847
32943
  "reflectToolTimeoutMs",
32944
+ "injectTimeoutMs",
32848
32945
  "pageSearchLimit",
32849
32946
  "pageRefreshEveryTurns",
32850
32947
  "seedLimit",
@@ -32893,15 +32990,25 @@ var BANK_OVERRIDE_EXCLUDED = [
32893
32990
  function applyBankConfig(cfg, resolvedId, directory) {
32894
32991
  if (directory !== void 0 && !isOptedIn(cfg, directory))
32895
32992
  return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
32993
+ const byPath = directory === void 0 ? void 0 : pathSection(cfg, cfg.paths, directory);
32994
+ if (byPath) {
32995
+ const { bank: _rename, ...rest } = overrideFields(byPath);
32996
+ cfg = { ...cfg, ...resolvePartial(cfg, rest) };
32997
+ }
32896
32998
  const section = cfg.banks[resolvedId];
32897
32999
  if (!section) return { cfg, bankId: resolvedId };
32898
- const safe = { ...section };
32899
- for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
32900
- delete safe.banks;
33000
+ const safe = overrideFields(section);
32901
33001
  const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
32902
33002
  delete safe.bank;
32903
33003
  return { cfg: { ...cfg, ...resolvePartial(cfg, safe) }, bankId };
32904
33004
  }
33005
+ function overrideFields(section) {
33006
+ const safe = { ...section };
33007
+ for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
33008
+ delete safe.banks;
33009
+ delete safe.paths;
33010
+ return safe;
33011
+ }
32905
33012
  function resolvePartial(cfg, patch) {
32906
33013
  const full = resolveConfig(patch);
32907
33014
  const out = {};
@@ -32910,6 +33017,16 @@ function resolvePartial(cfg, patch) {
32910
33017
  out[key] = full[key];
32911
33018
  }
32912
33019
  if ("autoReflect" in patch && !("autoInject" in patch)) out.autoInject = full.autoInject;
33020
+ if ("serverMode" in patch || "apiUrl" in patch || "apiPort" in patch) {
33021
+ const conn = resolveConfig({
33022
+ serverMode: patch.serverMode ?? cfg.serverMode,
33023
+ apiPort: patch.apiPort ?? cfg.apiPort,
33024
+ apiUrl: patch.apiUrl ?? (cfg.serverMode === "daemon" ? void 0 : cfg.apiUrl)
33025
+ });
33026
+ out.serverMode = conn.serverMode;
33027
+ out.apiUrl = conn.apiUrl;
33028
+ out.apiPort = conn.apiPort;
33029
+ }
32913
33030
  return out;
32914
33031
  }
32915
33032
 
@@ -32938,7 +33055,12 @@ function resolveHostMemory(harness, directory) {
32938
33055
  // rotate the key mid-session and the snapshot 401s every call until restart (#3600). Read
32939
33056
  // through the same pipeline the constructor used, so a per-bank `banks.<id>.apiToken` is
32940
33057
  // honoured on re-resolution exactly as it was on the first one.
32941
- tokenProvider: () => resolveHostConfig(harness, directory).cfg.apiToken
33058
+ // The URL stays the one this client was built with, so a token re-read after the config
33059
+ // moved this directory to ANOTHER server is that server's credential: never send it here.
33060
+ tokenProvider: () => {
33061
+ const live = resolveHostConfig(harness, directory).cfg;
33062
+ return live.apiUrl === cfg.apiUrl ? live.apiToken : cfg.apiToken;
33063
+ }
32942
33064
  })
32943
33065
  };
32944
33066
  }
@@ -32969,6 +33091,7 @@ function repoNameOf(repo) {
32969
33091
  return projectNameOf(resolve2(repo));
32970
33092
  }
32971
33093
  function commitsSince(dir, sinceSha) {
33094
+ if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(sinceSha)) return null;
32972
33095
  try {
32973
33096
  const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
32974
33097
  return Number.isFinite(n) ? n : null;
@@ -33098,19 +33221,7 @@ var NON_DESTRUCTIVE_WRITE_ANNOTATIONS = {
33098
33221
  idempotentHint: false,
33099
33222
  openWorldHint: false
33100
33223
  };
33101
- 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.';
33102
- function shapePage(page) {
33103
- const p = page ?? {};
33104
- const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
33105
- return {
33106
- id: p.id,
33107
- name: p.name,
33108
- ...p.description ? { description: p.description } : {},
33109
- ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
33110
- ...p.timestamp ? { last_updated_at: p.timestamp } : {},
33111
- body
33112
- };
33113
- }
33224
+ 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.';
33114
33225
  function ok(value) {
33115
33226
  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
33116
33227
  }
@@ -33128,6 +33239,8 @@ function guarded(fn) {
33128
33239
  };
33129
33240
  }
33130
33241
  function buildKnowledgeTools(client, bankId, opts = {}) {
33242
+ const extra = opts.toolGuideExtra?.trim();
33243
+ const crediting = extra ? `${CREDIT_REMINDER} ${extra}` : CREDIT_REMINDER;
33131
33244
  return [
33132
33245
  {
33133
33246
  name: "hindsight_sync_status",
@@ -33187,7 +33300,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
33187
33300
  },
33188
33301
  {
33189
33302
  name: "hindsight_search_knowledge_pages",
33190
- 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,
33303
+ 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,
33191
33304
  inputSchema: { query: external_exports.string().describe("what to look for") },
33192
33305
  annotations: READ_ONLY_ANNOTATIONS,
33193
33306
  handler: async (args) => {
@@ -33197,9 +33310,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
33197
33310
  pages: hits.map((h) => ({
33198
33311
  page: h.name,
33199
33312
  page_id: h.id,
33313
+ // The question the page answers — the same `description` the list and read tools
33314
+ // carry, so a hit says what the page is FOR, not just how it opens.
33315
+ ...h.source_query ? { description: h.source_query } : {},
33200
33316
  snippet: h.snippet
33201
33317
  })),
33202
- crediting: CREDIT_REMINDER
33318
+ crediting
33203
33319
  });
33204
33320
  } catch (e) {
33205
33321
  return err(e);
@@ -33218,7 +33334,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
33218
33334
  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.",
33219
33335
  inputSchema: { page_id: external_exports.string() },
33220
33336
  annotations: READ_ONLY_ANNOTATIONS,
33221
- handler: guarded(async ({ page_id }) => shapePage(await client.getPage(page_id)))
33337
+ handler: guarded(async ({ page_id }) => client.getPage(page_id))
33222
33338
  },
33223
33339
  {
33224
33340
  name: "hindsight_reflect",
@@ -33304,7 +33420,8 @@ function resolversFor(ctx) {
33304
33420
  function buildRetainStamp(cfg, ctx) {
33305
33421
  const hasTags = Boolean(cfg.retainTags?.length);
33306
33422
  const hasMetadata = Boolean(cfg.retainMetadata && Object.keys(cfg.retainMetadata).length);
33307
- if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
33423
+ const hasContext = Boolean(cfg.retainContext?.trim());
33424
+ if (!hasTags && !hasMetadata && !hasContext) return { tags: [], metadata: {} };
33308
33425
  const base = resolversFor(ctx);
33309
33426
  const cache = /* @__PURE__ */ new Map();
33310
33427
  const resolvers = Object.fromEntries(
@@ -33328,7 +33445,8 @@ function buildRetainStamp(cfg, ctx) {
33328
33445
  for (const [key, value] of Object.entries(cfg.retainMetadata ?? {})) {
33329
33446
  metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
33330
33447
  }
33331
- return { tags, metadata };
33448
+ const context = hasContext ? applyTemplate(cfg.retainContext, resolvers, "retainContext").trim() || void 0 : void 0;
33449
+ return { tags, metadata, context };
33332
33450
  }
33333
33451
 
33334
33452
  // src/mcp-server.ts
@@ -33341,6 +33459,7 @@ function selectTools(cfg, client, bankId, opts = {}) {
33341
33459
  pageTrigger: buildPageTrigger(cfg),
33342
33460
  reflectTimeoutMs: cfg.reflectToolTimeoutMs,
33343
33461
  reflectBudget: cfg.reflectBudget,
33462
+ toolGuideExtra: cfg.toolGuideExtra,
33344
33463
  stampFor: () => buildRetainStamp(cfg, { directory: cwd, harness, bankId })
33345
33464
  });
33346
33465
  }
@@ -33353,6 +33472,15 @@ function resolveHarness(env = process.env) {
33353
33472
  }
33354
33473
  return harness;
33355
33474
  }
33475
+ function resolveProjectCwd(env = process.env, argv = process.argv, fallbackCwd = process.cwd()) {
33476
+ const override = env.HINDSIGHT_MCP_PROJECT_CWD?.trim();
33477
+ if (override && !override.includes("${")) return override;
33478
+ if (env.HINDSIGHT_MCP_HARNESS === "cursor-cli") {
33479
+ const folder = argv[2]?.trim();
33480
+ if (folder && !folder.includes("${")) return folder;
33481
+ }
33482
+ return fallbackCwd;
33483
+ }
33356
33484
  function buildMcpServer(tools) {
33357
33485
  const server = new McpServer({ name: "hindsight", version: "0.1.0" });
33358
33486
  if (tools.length === 0) {
@@ -33374,7 +33502,7 @@ function buildMcpServer(tools) {
33374
33502
  return server;
33375
33503
  }
33376
33504
  async function main() {
33377
- const cwd = process.env.HINDSIGHT_MCP_PROJECT_CWD || process.cwd();
33505
+ const cwd = resolveProjectCwd();
33378
33506
  const harness = resolveHarness();
33379
33507
  const { cfg, bankId, client } = resolveHostMemory(harness, cwd);
33380
33508
  const server = buildMcpServer(selectTools(cfg, client, bankId, { cwd, harness }));
@@ -33389,5 +33517,6 @@ if (process.argv[1] && process.argv[1] === fileURLToPath3(import.meta.url)) {
33389
33517
  export {
33390
33518
  buildMcpServer,
33391
33519
  resolveHarness,
33520
+ resolveProjectCwd,
33392
33521
  selectTools
33393
33522
  };