@vectorize-io/hindsight-coding-agents 0.6.0 → 0.7.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 (50) hide show
  1. package/README.md +179 -40
  2. package/dist/antigravity-hook.js +344 -169
  3. package/dist/antigravity-statusline.js +117 -4
  4. package/dist/antigravity-stop-hook.js +262 -113
  5. package/dist/claude-hook.js +344 -169
  6. package/dist/claude-sessionstart-hook.js +348 -136
  7. package/dist/claude-stop-hook.js +262 -113
  8. package/dist/cline.js +494 -184
  9. package/dist/codex-hook.js +344 -169
  10. package/dist/codex-sessionstart-hook.js +348 -136
  11. package/dist/codex-stop-hook.js +262 -113
  12. package/dist/copilot-hook.js +344 -169
  13. package/dist/copilot-sessionstart-hook.js +348 -136
  14. package/dist/copilot-stop-hook.js +262 -113
  15. package/dist/cursor-hook.js +344 -169
  16. package/dist/cursor-sessionstart-hook.js +348 -136
  17. package/dist/cursor-stop-hook.js +262 -113
  18. package/dist/daemon-start.js +116 -4
  19. package/dist/dcode-hook.js +344 -169
  20. package/dist/dcode-sessionstart-hook.js +348 -136
  21. package/dist/dcode-stop-hook.js +262 -113
  22. package/dist/deepen.js +204 -47
  23. package/dist/devin-hook.js +344 -169
  24. package/dist/devin-sessionstart-hook.js +348 -136
  25. package/dist/devin-stop-hook.js +262 -113
  26. package/dist/droid-hook.js +344 -169
  27. package/dist/droid-sessionstart-hook.js +348 -136
  28. package/dist/droid-stop-hook.js +262 -113
  29. package/dist/dsh.js +494 -184
  30. package/dist/grok-hook.js +344 -169
  31. package/dist/grok-sessionstart-hook.js +348 -136
  32. package/dist/grok-stop-hook.js +262 -113
  33. package/dist/hindsight-seed.js +116 -4
  34. package/dist/index.js +494 -184
  35. package/dist/installer.js +92 -70
  36. package/dist/kilo.js +494 -184
  37. package/dist/mcp-server.js +230 -57
  38. package/dist/opencode2.js +521 -184
  39. package/dist/pi.js +495 -186
  40. package/dist/prime-agent.js +495 -186
  41. package/dist/qwen-hook.js +344 -169
  42. package/dist/qwen-sessionstart-hook.js +348 -136
  43. package/dist/qwen-stop-hook.js +262 -113
  44. package/dist/status.js +203 -47
  45. package/dist/zcode-hook.js +344 -169
  46. package/dist/zcode-sessionstart-hook.js +348 -136
  47. package/dist/zcode-stop-hook.js +262 -113
  48. package/package.json +2 -2
  49. package/plugin.json +1 -1
  50. package/skill/SKILL.md +173 -39
@@ -31610,13 +31610,15 @@ var CONVERSATION_MISSION = `You are ingesting a developer conversation as a JSON
31610
31610
  var REFLECT_MISSION = "You are a debugging assistant with the project's past decisions in memory (git rationale and developer chats). Given a bug's SYMPTOM, find the past decision whose rationale explains the ROOT CAUSE \u2014 not one that merely shares vocabulary. Answer with the PRECISE fix: state the EXACT rule and the LITERAL values, identifiers, strings, numbers, or set members that were decided \u2014 quote them VERBATIM, never paraphrase, generalize, or omit them (give the actual decided value, not 'the project standard'). If memories CONFLICT on the same rule, the LATEST decision wins \u2014 prefer facts that explicitly amend or supersede an earlier one, state the superseded rule as no longer in effect, and never present it as the fix. Name the function/file to change and cite the REF-ID(s). If NOTHING in memory genuinely explains THIS symptom, say exactly that in one short sentence \u2014 a wrong-but-confident nearest match is worse than an honest miss; never stretch an unrelated decision to fit.";
31611
31611
  var DOCUMENT_MISSION = "You are ingesting a standalone document (notes, docs, or structural findings). Extract the concrete facts, concepts, and structure it describes.";
31612
31612
  var OBSERVATIONS_MISSION = "Consolidate durable knowledge about THIS codebase \u2014 recurring patterns, conventions, module responsibilities, and how components relate \u2014 from the ingested commits and conversations. Favor stable structural understanding over one-off details. When a new fact contradicts or supersedes an existing observation, UPDATE that observation to reflect the current state rather than creating a sibling alongside it; note that the rule was revised and when, so the superseded version is visible as history rather than as a competing claim.";
31613
+ var RETAIN_EXTRACTION_MODES = ["concise", "verbose", "verbatim", "chunks"];
31614
+ var DEFAULT_RETAIN_EXTRACTION_MODE = "concise";
31613
31615
  var RETAIN_STRATEGIES = {
31614
- git: { retain_mission: GIT_MISSION, retain_extraction_mode: "verbose" },
31616
+ git: { retain_mission: GIT_MISSION, retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE },
31615
31617
  // ONE big aggregated document (last N commit messages, no diffs) -> a larger chunk size so it stays
31616
31618
  // in as few chunks as possible and the extractor sees the whole history arc at once.
31617
31619
  gitlog: {
31618
31620
  retain_mission: GITLOG_MISSION,
31619
- retain_extraction_mode: "verbose",
31621
+ retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE,
31620
31622
  retain_chunk_size: 12e3
31621
31623
  },
31622
31624
  // ONE strategy for ALL developer conversations — backfilled decision chats and live working
@@ -31627,15 +31629,15 @@ var RETAIN_STRATEGIES = {
31627
31629
  // the consolidation layer.
31628
31630
  conversation: {
31629
31631
  retain_mission: CONVERSATION_MISSION,
31630
- retain_extraction_mode: "verbose",
31632
+ retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE,
31631
31633
  retain_chunk_size: 12e3
31632
31634
  },
31633
31635
  // Structural documents (e.g. the codebase survey's ingested findings) aren't dialogue — the
31634
- // chat strategy's "final decision vs rejected proposal" extraction doesn't apply. Verbose mode
31635
- // with a bigger chunk size (documents can run long) captures the concrete facts/structure instead.
31636
+ // chat strategy's "final decision vs rejected proposal" extraction doesn't apply. A bigger chunk
31637
+ // size (documents can run long) keeps the concrete facts/structure together instead.
31636
31638
  document: {
31637
31639
  retain_mission: DOCUMENT_MISSION,
31638
- retain_extraction_mode: "verbose",
31640
+ retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE,
31639
31641
  retain_chunk_size: 12e3
31640
31642
  },
31641
31643
  // Codebase-SURVEY lifecycle documents, ONE strategy with conditional rules: the survey's
@@ -31708,9 +31710,22 @@ var PAGE_TAXONOMY = [
31708
31710
  tags: ["knowledge:feature-work"]
31709
31711
  }
31710
31712
  ];
31711
- function pagesFor(project) {
31713
+ var PAGE_NAMES = PAGE_TAXONOMY.map((page) => page.name);
31714
+ function pagesFor(project, pages = {}, customPages = {}) {
31712
31715
  const scope = pageScopeRule(project);
31713
- return PAGE_TAXONOMY.map((page) => ({ ...page, source_query: page.source_query + scope }));
31716
+ const byName = new Map(
31717
+ Object.entries(pages).map(([name, override]) => [name.trim().toLowerCase(), override])
31718
+ );
31719
+ const out = [];
31720
+ for (const page of PAGE_TAXONOMY) {
31721
+ const override = byName.get(page.name.toLowerCase());
31722
+ if (override === false) continue;
31723
+ out.push({ ...page, source_query: (override?.source_query || page.source_query) + scope });
31724
+ }
31725
+ for (const [name, page] of Object.entries(customPages)) {
31726
+ out.push({ name: name.trim(), source_query: page.source_query + scope, tags: page.tags ?? [] });
31727
+ }
31728
+ return out;
31714
31729
  }
31715
31730
  var PAGE_MAX_TOKENS = 4096;
31716
31731
  var PAGE_TAGS_MATCH = "all";
@@ -31793,7 +31808,7 @@ var CODING_BANK_TEMPLATE = {
31793
31808
  enable_observations: true,
31794
31809
  observations_mission: OBSERVATIONS_MISSION,
31795
31810
  retain_mission: GIT_MISSION,
31796
- retain_extraction_mode: "verbose",
31811
+ retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE,
31797
31812
  retain_default_strategy: "git",
31798
31813
  retain_strategies: RETAIN_STRATEGIES,
31799
31814
  entity_labels: [KNOWLEDGE_LABELS],
@@ -31806,7 +31821,7 @@ function isSet(v) {
31806
31821
  if (typeof v === "string") return v.trim() !== "";
31807
31822
  return true;
31808
31823
  }
31809
- function codingBankManifest(overrides) {
31824
+ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
31810
31825
  const current2 = overrides ?? {};
31811
31826
  const template = CODING_BANK_TEMPLATE.bank;
31812
31827
  const bank = {};
@@ -31815,16 +31830,22 @@ function codingBankManifest(overrides) {
31815
31830
  bank.enable_observations = template.enable_observations;
31816
31831
  bank.observations_mission = template.observations_mission;
31817
31832
  bank.retain_mission = template.retain_mission;
31818
- bank.retain_extraction_mode = template.retain_extraction_mode;
31833
+ bank.retain_extraction_mode = mode;
31819
31834
  }
31820
31835
  if (!isSet(current2.retain_default_strategy))
31821
31836
  bank.retain_default_strategy = template.retain_default_strategy;
31822
31837
  if (!isSet(current2.entities_allow_free_form))
31823
31838
  bank.entities_allow_free_form = template.entities_allow_free_form;
31824
31839
  const strategies = current2.retain_strategies && typeof current2.retain_strategies === "object" ? current2.retain_strategies : {};
31825
- const missing = Object.entries(template.retain_strategies).filter(([n]) => !(n in strategies));
31826
- if (missing.length > 0)
31827
- bank.retain_strategies = { ...strategies, ...Object.fromEntries(missing) };
31840
+ const updates = {};
31841
+ for (const [name, def] of Object.entries(template.retain_strategies)) {
31842
+ const synced = def.retain_extraction_mode === "custom" ? {} : { retain_extraction_mode: mode };
31843
+ const have = strategies[name];
31844
+ if (!have || typeof have !== "object") updates[name] = { ...def, ...synced };
31845
+ else if ("retain_extraction_mode" in synced && have.retain_extraction_mode !== mode)
31846
+ updates[name] = { ...have, ...synced };
31847
+ }
31848
+ if (Object.keys(updates).length > 0) bank.retain_strategies = { ...strategies, ...updates };
31828
31849
  const labels = Array.isArray(current2.entity_labels) ? current2.entity_labels : [];
31829
31850
  const [knowledgeGroup] = template.entity_labels;
31830
31851
  if (!labels.some((g) => g?.key === knowledgeGroup.key))
@@ -31896,6 +31917,14 @@ var KnowledgePagesUnavailableError = class extends Error {
31896
31917
  this.name = "KnowledgePagesUnavailableError";
31897
31918
  }
31898
31919
  };
31920
+ async function isEndpointMissing(r) {
31921
+ try {
31922
+ const j = await r.json();
31923
+ return String(j?.detail ?? "").trim().toLowerCase() === "not found";
31924
+ } catch {
31925
+ return true;
31926
+ }
31927
+ }
31899
31928
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
31900
31929
  var ReflectError = class extends Error {
31901
31930
  constructor(message, status, timedOut, options) {
@@ -31914,6 +31943,13 @@ var ReflectError = class extends Error {
31914
31943
  }
31915
31944
  };
31916
31945
  var DEFAULT_MAX_PARALLEL_RETAINS = 10;
31946
+ var DEFAULT_PAGE_SEARCH_LIMIT = 10;
31947
+ var DEFAULT_RECALL_OPTIONS = {
31948
+ types: ["observation"],
31949
+ budget: "low",
31950
+ max_tokens: 2e3,
31951
+ include: { entities: null }
31952
+ };
31917
31953
  var POLL_CYCLE_MS = 5e3;
31918
31954
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
31919
31955
  var RETRY_AFTER_CEILING_MS = 60 * 1e3;
@@ -31934,6 +31970,8 @@ var HindsightClient = class {
31934
31970
  log;
31935
31971
  maxParallelRetains;
31936
31972
  observationScopes;
31973
+ pageSearchLimit;
31974
+ recallOptions;
31937
31975
  constructor(o) {
31938
31976
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
31939
31977
  this.token = o.apiToken;
@@ -31944,6 +31982,8 @@ var HindsightClient = class {
31944
31982
  });
31945
31983
  this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
31946
31984
  this.observationScopes = o.observationScopes ?? DEFAULT_OBSERVATION_SCOPES;
31985
+ this.pageSearchLimit = o.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT;
31986
+ this.recallOptions = { ...DEFAULT_RECALL_OPTIONS, ...o.recallOptions };
31947
31987
  }
31948
31988
  /** The credential in use, for diagnostics. Never log or report the VALUE — booleans only. */
31949
31989
  get apiToken() {
@@ -32085,7 +32125,8 @@ var HindsightClient = class {
32085
32125
  }
32086
32126
  /** Configure the bank: POST the coding bank manifest to /import (missions, retain strategies,
32087
32127
  * entity labels), then seed knowledge pages when the server supports them. Both halves are
32088
- * idempotent and strictly ADDITIVE — nothing the bank already says is overwritten (#3927) — so
32128
+ * idempotent and ADDITIVE — nothing the bank already says is overwritten (#3927), bar the
32129
+ * extraction mode of the plugin's own strategies, which follows its config (#4560) — so
32089
32130
  * the deepen engine can re-run this every pass. Creates the bank if missing; legacy servers
32090
32131
  * continue with the template-only path.
32091
32132
  *
@@ -32101,7 +32142,10 @@ var HindsightClient = class {
32101
32142
  if (opts.manage === false) {
32102
32143
  this.log(`[bank] manageBankConfig: false \u2014 leaving ${this.bank}'s configuration alone`);
32103
32144
  } else {
32104
- const manifest = codingBankManifest(opts.reset ? void 0 : await this.readBankOverrides());
32145
+ const manifest = codingBankManifest(
32146
+ opts.reset ? void 0 : await this.readBankOverrides(),
32147
+ opts.extractionMode
32148
+ );
32105
32149
  if (!manifest) {
32106
32150
  this.log(`[bank] ${this.bank} already carries the coding structure \u2014 nothing to apply`);
32107
32151
  } else {
@@ -32109,7 +32153,7 @@ var HindsightClient = class {
32109
32153
  this.log(`[bank] applied to ${this.bank}: ${Object.keys(manifest.bank).sort().join(", ")}`);
32110
32154
  }
32111
32155
  }
32112
- await this.seedPages(opts.pageTrigger);
32156
+ await this.seedPages(opts.pageTrigger, opts.pages, opts.customPages);
32113
32157
  }
32114
32158
  /**
32115
32159
  * This bank's own config OVERRIDES, or undefined when there are none to read.
@@ -32225,20 +32269,22 @@ var HindsightClient = class {
32225
32269
  }
32226
32270
  }
32227
32271
  /**
32228
- * Raw recall restricted to consolidated observations — no LLM in the loop, so it still answers
32229
- * when reflect's synthesis times out or 5xxs. Returns the observation texts in rank order.
32272
+ * Raw recall with no LLM in the loop, so it still answers when reflect's synthesis times out or
32273
+ * 5xxs. The body is `recallOptions` (consolidated observations by default) — a bank that grows
32274
+ * no observations widens it rather than getting nothing back. Returns the texts in rank order.
32275
+ *
32276
+ * The name predates `recallOptions` (the observation type used to be hardcoded here) and is
32277
+ * kept deliberately: this is the client's published surface, so renaming it would break
32278
+ * importers for a cosmetic gain. The doc above is the contract, not the name.
32230
32279
  */
32231
32280
  async recallObservations(query, opts) {
32232
32281
  const r = await this.req(
32233
32282
  "POST",
32234
32283
  this.bankUrl("/memories/recall"),
32235
- {
32236
- query,
32237
- types: ["observation"],
32238
- budget: "low",
32239
- max_tokens: opts.maxTokens,
32240
- include: { entities: null }
32241
- },
32284
+ // `query` is applied AFTER the spread: everything else is the caller's to override, but a
32285
+ // config that could replace the goal with a fixed string would silently recall for the
32286
+ // wrong question on every turn.
32287
+ { ...this.recallOptions, query },
32242
32288
  [],
32243
32289
  opts.timeoutMs
32244
32290
  );
@@ -32246,6 +32292,19 @@ var HindsightClient = class {
32246
32292
  const j = await r.json();
32247
32293
  return (j.results ?? []).map((x) => (x.text ?? "").trim()).filter(Boolean);
32248
32294
  }
32295
+ /**
32296
+ * Latch `knowledgePagesSupported = false` iff this response really means the endpoint is absent.
32297
+ * Returns whether it latched. A bank-not-found 404 is NOT a capability verdict — it is the
32298
+ * expected answer before the bank's first retain — so it must never cache a negative (#4607).
32299
+ *
32300
+ * Only 404 is tested: `req` throws on every other non-ok status it was not told to tolerate, so
32301
+ * the 405/501 this used to check for never reach a caller in the first place.
32302
+ */
32303
+ async pagesUnsupported(r) {
32304
+ if (r.status !== 404 || !await isEndpointMissing(r)) return false;
32305
+ this.knowledgePagesSupported = false;
32306
+ return true;
32307
+ }
32249
32308
  /**
32250
32309
  * The bank's knowledge-base tree (folders + pages, nested). The tree carries names, source
32251
32310
  * queries and staleness but NOT synthesized content, so it is cheap enough to poll.
@@ -32253,10 +32312,8 @@ var HindsightClient = class {
32253
32312
  async tree() {
32254
32313
  if (this.knowledgePagesSupported === false) throw new KnowledgePagesUnavailableError();
32255
32314
  const r = await this.req("GET", this.bankUrl("/knowledge-base/tree"));
32256
- if ([404, 405, 501].includes(r.status)) {
32257
- this.knowledgePagesSupported = false;
32258
- throw new KnowledgePagesUnavailableError();
32259
- }
32315
+ if (await this.pagesUnsupported(r)) throw new KnowledgePagesUnavailableError();
32316
+ if (r.status === 404) return [];
32260
32317
  this.knowledgePagesSupported = true;
32261
32318
  try {
32262
32319
  return (await r.json()).roots ?? [];
@@ -32310,16 +32367,18 @@ var HindsightClient = class {
32310
32367
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
32311
32368
  * Returns page-level hits with a relevance snippet — the real search behind
32312
32369
  * hindsight_search_knowledge_pages. */
32313
- async searchKnowledgePages(query, limit = 3, timeoutMs) {
32370
+ async searchKnowledgePages(query, opts = {}) {
32314
32371
  if (this.knowledgePagesSupported === false) throw new KnowledgePagesUnavailableError();
32315
- const q = `?q=${encodeURIComponent(query)}&limit=${limit}`;
32372
+ const q = `?q=${encodeURIComponent(query)}&limit=${opts.limit ?? this.pageSearchLimit}`;
32316
32373
  const r = await this.req(
32317
32374
  "GET",
32318
32375
  this.bankUrl(`/knowledge-base/search${q}`),
32319
32376
  void 0,
32320
32377
  [],
32321
- timeoutMs
32378
+ opts.timeoutMs
32322
32379
  );
32380
+ if (await this.pagesUnsupported(r)) throw new KnowledgePagesUnavailableError();
32381
+ if (r.status === 404) return [];
32323
32382
  const j = await r.json();
32324
32383
  return (j.results ?? []).map((x) => ({
32325
32384
  id: x.id,
@@ -32339,8 +32398,8 @@ var HindsightClient = class {
32339
32398
  * `source_query` re-syncs onto the live page instead of orphaning its synthesized content —
32340
32399
  * which is how `pageScopeRule`'s repo name reaches banks seeded by an earlier version.
32341
32400
  */
32342
- async seedPages(pageTrigger = buildPageTrigger()) {
32343
- const pages = pagesFor(this.project ?? this.bank);
32401
+ async seedPages(pageTrigger = buildPageTrigger(), pagesConfig = {}, customPages = {}) {
32402
+ const pages = pagesFor(this.project ?? this.bank, pagesConfig, customPages);
32344
32403
  const existing = /* @__PURE__ */ new Map();
32345
32404
  let roots;
32346
32405
  try {
@@ -32357,6 +32416,7 @@ var HindsightClient = class {
32357
32416
  }
32358
32417
  let created = 0;
32359
32418
  let updated = 0;
32419
+ let vanished = 0;
32360
32420
  for (const page of pages) {
32361
32421
  const hit = existing.get(page.name.toLowerCase());
32362
32422
  const body = {
@@ -32370,13 +32430,16 @@ var HindsightClient = class {
32370
32430
  };
32371
32431
  if (!hit) {
32372
32432
  const r = await this.req("POST", this.bankUrl("/knowledge-base/pages"), body, [409]);
32373
- if ([404, 405, 501].includes(r.status)) {
32374
- this.knowledgePagesSupported = false;
32433
+ if (await this.pagesUnsupported(r)) {
32375
32434
  this.log(
32376
32435
  `[bank] knowledge pages unavailable on ${this.apiUrl}; continuing without pages`
32377
32436
  );
32378
32437
  return;
32379
32438
  }
32439
+ if (r.status === 404) {
32440
+ this.log(`[bank] ${this.bank} does not exist yet; pages seed on the next session`);
32441
+ return;
32442
+ }
32380
32443
  if (r.status !== 409) created++;
32381
32444
  } else {
32382
32445
  const sourceDrift = hit.description !== page.source_query;
@@ -32386,6 +32449,9 @@ var HindsightClient = class {
32386
32449
  if (sourceDrift) {
32387
32450
  patch.source_query = page.source_query;
32388
32451
  patch.tags = page.tags;
32452
+ this.log(
32453
+ `[bank] re-syncing "${page.name}" to its configured source_query \u2014 set pages[${JSON.stringify(page.name)}].source_query to keep your own wording`
32454
+ );
32389
32455
  }
32390
32456
  if (triggerDrift) patch.trigger = pageTriggerPatch(body.trigger);
32391
32457
  const r = await this.req(
@@ -32393,19 +32459,22 @@ var HindsightClient = class {
32393
32459
  this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(hit.id)}`),
32394
32460
  patch
32395
32461
  );
32396
- if ([404, 405, 501].includes(r.status)) {
32397
- this.knowledgePagesSupported = false;
32462
+ if (await this.pagesUnsupported(r)) {
32398
32463
  this.log(
32399
32464
  `[bank] knowledge pages unavailable on ${this.apiUrl}; continuing without pages`
32400
32465
  );
32401
32466
  return;
32402
32467
  }
32468
+ if (r.status === 404) {
32469
+ vanished++;
32470
+ continue;
32471
+ }
32403
32472
  updated++;
32404
32473
  }
32405
32474
  }
32406
32475
  const initiatives = await this.resyncInitiativeTriggers(roots, pageTrigger);
32407
32476
  this.log(
32408
- `[bank] knowledge pages seeded on ${this.bank} (scoped to ${this.project ?? this.bank}): ${created} created, ${updated} re-synced, ${pages.length - created - updated} unchanged` + (initiatives ? `, ${initiatives} initiative pages re-synced` : "")
32477
+ `[bank] knowledge pages seeded on ${this.bank} (scoped to ${this.project ?? this.bank}): ${created} created, ${updated} re-synced, ${pages.length - created - updated - vanished} unchanged` + (vanished ? `, ${vanished} deleted under us` : "") + (initiatives ? `, ${initiatives} initiative pages re-synced` : "")
32409
32478
  );
32410
32479
  }
32411
32480
  /**
@@ -32434,7 +32503,7 @@ var HindsightClient = class {
32434
32503
  this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(page.id)}`),
32435
32504
  { trigger: pageTriggerPatch(desired) }
32436
32505
  );
32437
- if ([404, 405, 501].includes(r.status)) break;
32506
+ if (r.status === 404) continue;
32438
32507
  updated++;
32439
32508
  }
32440
32509
  return updated;
@@ -32526,6 +32595,63 @@ function resolvePageTrigger(raw) {
32526
32595
  );
32527
32596
  return { type: "cron", cron: DEFAULT_PAGE_TRIGGER_CRON };
32528
32597
  }
32598
+ function resolvePages(raw) {
32599
+ const value = raw;
32600
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
32601
+ const out = {};
32602
+ for (const [name, entry] of Object.entries(value)) {
32603
+ if (!PAGE_NAMES.some((known) => known.toLowerCase() === name.trim().toLowerCase())) {
32604
+ log.warn(
32605
+ "config",
32606
+ `ignoring pages[${JSON.stringify(name)}] \u2014 no seeded page has that name; expected one of: ${PAGE_NAMES.join(", ")}`
32607
+ );
32608
+ continue;
32609
+ }
32610
+ if (entry === false) {
32611
+ out[name] = false;
32612
+ continue;
32613
+ }
32614
+ const query = entry && typeof entry === "object" && !Array.isArray(entry) ? entry.source_query : void 0;
32615
+ if (typeof query === "string" && query.trim()) {
32616
+ out[name] = { source_query: query };
32617
+ continue;
32618
+ }
32619
+ log.warn(
32620
+ "config",
32621
+ `ignoring pages[${JSON.stringify(name)}]=${JSON.stringify(entry)} \u2014 expected false, or {"source_query": "<your question>"}`
32622
+ );
32623
+ }
32624
+ return out;
32625
+ }
32626
+ function resolveCustomPages(raw) {
32627
+ const value = raw;
32628
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
32629
+ const out = {};
32630
+ for (const [rawName, entry] of Object.entries(value)) {
32631
+ const name = rawName.trim();
32632
+ if (!name) continue;
32633
+ if (PAGE_NAMES.some((known) => known.toLowerCase() === name.toLowerCase())) {
32634
+ log.warn(
32635
+ "config",
32636
+ `ignoring customPages[${JSON.stringify(rawName)}] \u2014 that is a seeded page; reword it under \`pages\` instead`
32637
+ );
32638
+ continue;
32639
+ }
32640
+ const query = entry && typeof entry === "object" && !Array.isArray(entry) ? entry.source_query : void 0;
32641
+ if (typeof query !== "string" || !query.trim()) {
32642
+ log.warn(
32643
+ "config",
32644
+ `ignoring customPages[${JSON.stringify(rawName)}]=${JSON.stringify(entry)} \u2014 expected {"source_query": "<your question>"}`
32645
+ );
32646
+ continue;
32647
+ }
32648
+ const rawTags = entry.tags;
32649
+ const tags = Array.isArray(rawTags) ? rawTags.filter((t) => typeof t === "string" && t.trim() !== "") : [];
32650
+ out[name] = tags.length ? { source_query: query, tags } : { source_query: query };
32651
+ }
32652
+ return out;
32653
+ }
32654
+ var DEFAULT_REFLECT_TIMEOUT_MS = 2e4;
32529
32655
  var DEFAULT_REFLECT_TOOL_TIMEOUT_MS = 33e4;
32530
32656
  var REFLECT_BUDGETS = ["low", "mid", "high"];
32531
32657
  function resolveReflectBudget(raw) {
@@ -32553,6 +32679,15 @@ function resolveObservationScopes(raw) {
32553
32679
  }
32554
32680
  return DEFAULT_OBSERVATION_SCOPES;
32555
32681
  }
32682
+ var AUTO_INJECT_MODES = ["reflect", "pages", "recall", "none"];
32683
+ function resolveAutoInject(raw) {
32684
+ if (raw.autoReflect !== void 0) {
32685
+ const replacement = raw.autoReflect === false ? "none" : "reflect";
32686
+ log.warn("config", `autoReflect is deprecated \u2014 use autoInject: "${replacement}" instead`);
32687
+ }
32688
+ if (AUTO_INJECT_MODES.includes(raw.autoInject)) return raw.autoInject;
32689
+ return raw.autoReflect === false ? "none" : "reflect";
32690
+ }
32556
32691
  function resolveConfig(raw = {}) {
32557
32692
  const serverMode = ["cloud", "self-hosted", "daemon"].includes(raw.serverMode) ? raw.serverMode : "cloud";
32558
32693
  const apiPort = raw.apiPort || DEFAULT_DAEMON_PORT;
@@ -32582,17 +32717,28 @@ function resolveConfig(raw = {}) {
32582
32717
  retainSessions: raw.retainSessions ?? true,
32583
32718
  // write sessions back by default, every harness
32584
32719
  manageBankConfig: raw.manageBankConfig ?? true,
32720
+ retainExtractionMode: RETAIN_EXTRACTION_MODES.includes(raw.retainExtractionMode) ? raw.retainExtractionMode : DEFAULT_RETAIN_EXTRACTION_MODE,
32585
32721
  maxParallelRetains: raw.maxParallelRetains || 10,
32586
- reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
32722
+ reflectTimeoutMs: raw.reflectTimeoutMs || DEFAULT_REFLECT_TIMEOUT_MS,
32587
32723
  // Inherit an explicitly-raised reflectTimeoutMs (that is what users reaching for a longer
32588
32724
  // reflect already set), but never let it LOWER the tool below the default — a short window is
32589
32725
  // set to bound the automatic hook, not to cut off a call the agent is waiting on.
32590
32726
  reflectToolTimeoutMs: raw.reflectToolTimeoutMs || Math.max(raw.reflectTimeoutMs || 0, DEFAULT_REFLECT_TOOL_TIMEOUT_MS),
32591
32727
  reflectBudget: resolveReflectBudget(raw),
32592
- autoReflect: raw.autoReflect ?? true,
32593
- pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
32728
+ autoInject: resolveAutoInject(raw),
32729
+ pageSearchLimit: raw.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT,
32730
+ // Same shape as retainMetadata: an object, or nothing. An array would spread into numeric
32731
+ // keys and reach the API as garbage, so it is rejected like any other non-object.
32732
+ recallOptions: raw.recallOptions && typeof raw.recallOptions === "object" && !Array.isArray(raw.recallOptions) ? { ...raw.recallOptions } : {},
32733
+ // Every turn, not every tenth. The guide is what tells the agent WHEN to reach for memory, and
32734
+ // at a cadence of 10 a normal session is told once, on turn 1, and never again. Measured over
32735
+ // 40 real Claude Code turns, moving this from 10 to 1 took searches from 15% of turns to 32.5%
32736
+ // with no wording change at all. The cost is the guide's ~2KB re-sent per turn, which caches.
32737
+ pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 1,
32594
32738
  pageTriggerType: pageTrigger.type,
32595
32739
  pageTriggerCron: pageTrigger.cron,
32740
+ pages: resolvePages(raw.pages),
32741
+ customPages: resolveCustomPages(raw.customPages),
32596
32742
  autoSeed: raw.autoSeed ?? true,
32597
32743
  seedLimit: raw.seedLimit || DEFAULT_SEED_LIMIT,
32598
32744
  codebaseSurvey: raw.codebaseSurvey ?? true,
@@ -32656,6 +32802,8 @@ var ENV_KEYS = {
32656
32802
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
32657
32803
  reflectToolTimeoutMs: "HINDSIGHT_REFLECT_TOOL_TIMEOUT_MS",
32658
32804
  reflectBudget: "HINDSIGHT_REFLECT_BUDGET",
32805
+ autoInject: "HINDSIGHT_AUTO_INJECT",
32806
+ pageSearchLimit: "HINDSIGHT_PAGE_SEARCH_LIMIT",
32659
32807
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
32660
32808
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
32661
32809
  pageTriggerType: "HINDSIGHT_PAGE_TRIGGER_TYPE",
@@ -32675,7 +32823,8 @@ var ENV_KEYS = {
32675
32823
  // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
32676
32824
  // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
32677
32825
  retainTags: "HINDSIGHT_RETAIN_TAGS",
32678
- manageBankConfig: "HINDSIGHT_MANAGE_BANK_CONFIG"
32826
+ manageBankConfig: "HINDSIGHT_MANAGE_BANK_CONFIG",
32827
+ retainExtractionMode: "HINDSIGHT_RETAIN_EXTRACTION_MODE"
32679
32828
  };
32680
32829
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
32681
32830
  "dynamicBankId",
@@ -32696,6 +32845,7 @@ var ENV_NUMBERS = /* @__PURE__ */ new Set([
32696
32845
  "maxParallelRetains",
32697
32846
  "reflectTimeoutMs",
32698
32847
  "reflectToolTimeoutMs",
32848
+ "pageSearchLimit",
32699
32849
  "pageRefreshEveryTurns",
32700
32850
  "seedLimit",
32701
32851
  "surveyBudgetUsd",
@@ -32759,6 +32909,7 @@ function resolvePartial(cfg, patch) {
32759
32909
  if (key in full)
32760
32910
  out[key] = full[key];
32761
32911
  }
32912
+ if ("autoReflect" in patch && !("autoInject" in patch)) out.autoInject = full.autoInject;
32762
32913
  return out;
32763
32914
  }
32764
32915
 
@@ -32781,6 +32932,8 @@ function resolveHostMemory(harness, directory) {
32781
32932
  bank: bankId,
32782
32933
  maxParallelRetains: cfg.maxParallelRetains,
32783
32934
  observationScopes: cfg.observationScopes,
32935
+ pageSearchLimit: cfg.pageSearchLimit,
32936
+ recallOptions: cfg.recallOptions,
32784
32937
  // The credential a host STARTED with is not the one it must keep using: enable auth or
32785
32938
  // rotate the key mid-session and the snapshot 401s every call until restart (#3600). Read
32786
32939
  // through the same pipeline the constructor used, so a per-bank `banks.<id>.apiToken` is
@@ -32791,6 +32944,7 @@ function resolveHostMemory(harness, directory) {
32791
32944
  }
32792
32945
 
32793
32946
  // src/core/knowledge-tools.ts
32947
+ import { createHash as createHash3 } from "crypto";
32794
32948
  import { existsSync as existsSync3 } from "fs";
32795
32949
  import { homedir as homedir5 } from "os";
32796
32950
  import { join as join10 } from "path";
@@ -32805,7 +32959,10 @@ function git(repo, ...args) {
32805
32959
  return execFileSync("git", ["-C", repo, ...args], {
32806
32960
  encoding: "utf8",
32807
32961
  maxBuffer: 1 << 28,
32808
- windowsHide: true
32962
+ windowsHide: true,
32963
+ // execFileSync otherwise forwards failed git stderr into the host's TUI,
32964
+ // even when callers catch the error. Keep diagnostics on the error instead.
32965
+ stdio: ["ignore", "pipe", "pipe"]
32809
32966
  });
32810
32967
  }
32811
32968
  function repoNameOf(repo) {
@@ -32872,7 +33029,9 @@ function commitCount(repoDir) {
32872
33029
  try {
32873
33030
  const out = execFileSync2("git", ["-C", repoDir, "rev-list", "--count", "HEAD"], {
32874
33031
  encoding: "utf8",
32875
- windowsHide: true
33032
+ windowsHide: true,
33033
+ stdio: ["ignore", "pipe", "pipe"]
33034
+ // failed probes must not write into the host TUI
32876
33035
  });
32877
33036
  return Number(out.trim()) || 0;
32878
33037
  } catch {
@@ -32939,6 +33098,19 @@ var NON_DESTRUCTIVE_WRITE_ANNOTATIONS = {
32939
33098
  idempotentHint: false,
32940
33099
  openWorldHint: false
32941
33100
  };
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
+ }
32942
33114
  function ok(value) {
32943
33115
  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
32944
33116
  }
@@ -33015,20 +33187,20 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
33015
33187
  },
33016
33188
  {
33017
33189
  name: "hindsight_search_knowledge_pages",
33018
- 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. When a result informs your answer, credit it visibly: start that part with a markdown blockquote header "> \u{1F9E0} **From Hindsight memory (<page name>)** \u2014 <the facts you drew on>".`,
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,
33019
33191
  inputSchema: { query: external_exports.string().describe("what to look for") },
33020
33192
  annotations: READ_ONLY_ANNOTATIONS,
33021
33193
  handler: async (args) => {
33022
33194
  try {
33023
- const hits = await client.searchKnowledgePages(args.query, 3);
33024
- return ok(
33025
- hits.map((h) => ({
33195
+ const hits = await client.searchKnowledgePages(args.query);
33196
+ return ok({
33197
+ pages: hits.map((h) => ({
33026
33198
  page: h.name,
33027
33199
  page_id: h.id,
33028
- snippet: h.snippet,
33029
- score: h.score
33030
- }))
33031
- );
33200
+ snippet: h.snippet
33201
+ })),
33202
+ crediting: CREDIT_REMINDER
33203
+ });
33032
33204
  } catch (e) {
33033
33205
  return err(e);
33034
33206
  }
@@ -33046,7 +33218,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
33046
33218
  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.",
33047
33219
  inputSchema: { page_id: external_exports.string() },
33048
33220
  annotations: READ_ONLY_ANNOTATIONS,
33049
- handler: guarded(async ({ page_id }) => client.getPage(page_id))
33221
+ handler: guarded(async ({ page_id }) => shapePage(await client.getPage(page_id)))
33050
33222
  },
33051
33223
  {
33052
33224
  name: "hindsight_reflect",
@@ -33085,7 +33257,8 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
33085
33257
  inputSchema: { title: external_exports.string(), content: external_exports.string() },
33086
33258
  annotations: NON_DESTRUCTIVE_WRITE_ANNOTATIONS,
33087
33259
  handler: guarded(async ({ title, content }) => {
33088
- const docId = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "doc";
33260
+ const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
33261
+ const docId = /[^\x00-\x7f]/.test(title) || !slug ? `${slug || "doc"}--${createHash3("sha256").update(title).digest("hex")}` : slug;
33089
33262
  const stamp = opts.stampFor?.();
33090
33263
  const metadata = {
33091
33264
  ...stamp?.metadata,