@vectorize-io/hindsight-coding-agents 0.5.4 → 0.5.5

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 (46) hide show
  1. package/README.md +5 -2
  2. package/dist/antigravity-hook.js +121 -11
  3. package/dist/antigravity-stop-hook.js +56 -8
  4. package/dist/claude-hook.js +121 -11
  5. package/dist/claude-sessionstart-hook.js +56 -8
  6. package/dist/claude-stop-hook.js +56 -8
  7. package/dist/cline.js +121 -11
  8. package/dist/codex-hook.js +121 -11
  9. package/dist/codex-sessionstart-hook.js +56 -8
  10. package/dist/codex-stop-hook.js +56 -8
  11. package/dist/copilot-hook.js +121 -11
  12. package/dist/copilot-sessionstart-hook.js +56 -8
  13. package/dist/copilot-stop-hook.js +56 -8
  14. package/dist/cursor-hook.js +121 -11
  15. package/dist/cursor-sessionstart-hook.js +56 -8
  16. package/dist/cursor-stop-hook.js +56 -8
  17. package/dist/dcode-hook.js +121 -11
  18. package/dist/dcode-sessionstart-hook.js +56 -8
  19. package/dist/dcode-stop-hook.js +56 -8
  20. package/dist/deepen.js +56 -8
  21. package/dist/devin-hook.js +121 -11
  22. package/dist/devin-sessionstart-hook.js +56 -8
  23. package/dist/devin-stop-hook.js +56 -8
  24. package/dist/droid-hook.js +121 -11
  25. package/dist/droid-sessionstart-hook.js +56 -8
  26. package/dist/droid-stop-hook.js +56 -8
  27. package/dist/dsh.js +121 -11
  28. package/dist/grok-hook.js +121 -11
  29. package/dist/grok-sessionstart-hook.js +56 -8
  30. package/dist/grok-stop-hook.js +56 -8
  31. package/dist/index.js +121 -11
  32. package/dist/kilo.js +121 -11
  33. package/dist/mcp-server.js +56 -8
  34. package/dist/opencode2.js +121 -11
  35. package/dist/pi.js +121 -11
  36. package/dist/prime-agent.js +121 -11
  37. package/dist/qwen-hook.js +121 -11
  38. package/dist/qwen-sessionstart-hook.js +56 -8
  39. package/dist/qwen-stop-hook.js +56 -8
  40. package/dist/status.js +56 -8
  41. package/dist/zcode-hook.js +121 -11
  42. package/dist/zcode-sessionstart-hook.js +56 -8
  43. package/dist/zcode-stop-hook.js +56 -8
  44. package/package.json +1 -1
  45. package/plugin.json +1 -1
  46. package/skill/SKILL.md +5 -2
package/dist/dsh.js CHANGED
@@ -679,6 +679,22 @@ var KnowledgePagesUnavailableError = class extends Error {
679
679
  }
680
680
  };
681
681
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
682
+ var ReflectError = class extends Error {
683
+ constructor(message, status, timedOut, options) {
684
+ super(message, options);
685
+ this.status = status;
686
+ this.timedOut = timedOut;
687
+ this.name = "ReflectError";
688
+ }
689
+ status;
690
+ timedOut;
691
+ /** A timeout or a 5xx means reflect's synthesis (the slow LLM path) broke, while the cheap
692
+ * retrieval endpoints may still answer — worth falling back. A 4xx will fail the same way on
693
+ * every endpoint (auth, missing bank), so it is not. */
694
+ get fallbackEligible() {
695
+ return this.timedOut || this.status !== void 0 && this.status >= 500;
696
+ }
697
+ };
682
698
  var DEFAULT_MAX_PARALLEL_RETAINS = 10;
683
699
  var POLL_CYCLE_MS = 5e3;
684
700
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
@@ -762,11 +778,11 @@ var HindsightClient = class {
762
778
  return `${this.apiUrl}/v1/default/banks/${encodeURIComponent(this.bank)}${suffix}`;
763
779
  }
764
780
  /** `tolerate` adds statuses that are returned to the caller instead of thrown (404 always is). */
765
- async req(method, url2, body, tolerate = []) {
781
+ async req(method, url2, body, tolerate = [], timeoutMs = 15e3) {
766
782
  const r = await this.fetchWithAuth(url2, {
767
783
  method,
768
784
  body: body ? JSON.stringify(body) : void 0,
769
- signal: AbortSignal.timeout(15e3)
785
+ signal: AbortSignal.timeout(timeoutMs)
770
786
  });
771
787
  if (r.status === 429 && !tolerate.includes(429))
772
788
  throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
@@ -959,7 +975,7 @@ var HindsightClient = class {
959
975
  /**
960
976
  * Reflect: synthesized, root-cause answer over the bank. Bounded so a slow server never hangs a
961
977
  * caller — but `timeoutMs` is REQUIRED, deliberately: the right deadline differs by an order of
962
- * magnitude between the automatic hook (25s, to fit the host's window) and the agent-invoked
978
+ * magnitude between the automatic hook (20s, to fit the host's window) and the agent-invoked
963
979
  * tool (minutes, on a populated bank). This used to default to 120s, which silently overrode the
964
980
  * tool's configured window and aborted every high-budget synthesis mid-flight (#3590).
965
981
  */
@@ -973,19 +989,45 @@ var HindsightClient = class {
973
989
  signal: ctrl.signal
974
990
  });
975
991
  if (!resp.ok)
976
- throw new Error(
977
- `reflect ${resp.status} ${(await resp.text()).slice(0, 1e3)}${this.authHint(resp.status)}`
992
+ throw new ReflectError(
993
+ `reflect ${resp.status} ${(await resp.text()).slice(0, 1e3)}${this.authHint(resp.status)}`,
994
+ resp.status,
995
+ false
978
996
  );
979
997
  const data = await resp.json();
980
998
  return (data.text || "").trim();
981
999
  } catch (e) {
982
1000
  if (ctrl.signal.aborted)
983
- throw new Error(`reflect timed out after ${opts.timeoutMs}ms`, { cause: e });
1001
+ throw new ReflectError(`reflect timed out after ${opts.timeoutMs}ms`, void 0, true, {
1002
+ cause: e
1003
+ });
984
1004
  throw e;
985
1005
  } finally {
986
1006
  clearTimeout(timer);
987
1007
  }
988
1008
  }
1009
+ /**
1010
+ * Raw recall restricted to consolidated observations — no LLM in the loop, so it still answers
1011
+ * when reflect's synthesis times out or 5xxs. Returns the observation texts in rank order.
1012
+ */
1013
+ async recallObservations(query, opts) {
1014
+ const r = await this.req(
1015
+ "POST",
1016
+ this.bankUrl("/memories/recall"),
1017
+ {
1018
+ query,
1019
+ types: ["observation"],
1020
+ budget: "low",
1021
+ max_tokens: opts.maxTokens,
1022
+ include: { entities: null }
1023
+ },
1024
+ [],
1025
+ opts.timeoutMs
1026
+ );
1027
+ if (r.status === 404) return [];
1028
+ const j = await r.json();
1029
+ return (j.results ?? []).map((x) => (x.text ?? "").trim()).filter(Boolean);
1030
+ }
989
1031
  /**
990
1032
  * The bank's knowledge-base tree (folders + pages, nested). The tree carries names, source
991
1033
  * queries and staleness but NOT synthesized content, so it is cheap enough to poll.
@@ -1050,10 +1092,16 @@ var HindsightClient = class {
1050
1092
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
1051
1093
  * Returns page-level hits with a relevance snippet — the real search behind
1052
1094
  * hindsight_search_knowledge_pages. */
1053
- async searchKnowledgePages(query, limit = 3) {
1095
+ async searchKnowledgePages(query, limit = 3, timeoutMs) {
1054
1096
  if (this.knowledgePagesSupported === false) throw new KnowledgePagesUnavailableError();
1055
1097
  const q = `?q=${encodeURIComponent(query)}&limit=${limit}`;
1056
- const r = await this.req("GET", this.bankUrl(`/knowledge-base/search${q}`));
1098
+ const r = await this.req(
1099
+ "GET",
1100
+ this.bankUrl(`/knowledge-base/search${q}`),
1101
+ void 0,
1102
+ [],
1103
+ timeoutMs
1104
+ );
1057
1105
  const j = await r.json();
1058
1106
  return (j.results ?? []).map((x) => ({
1059
1107
  id: x.id,
@@ -17484,6 +17532,15 @@ Report what this bank's history genuinely bears on that goal. Rendering rules, s
17484
17532
  - Do not connect unrelated episodes into one narrative; if two facts are not explicitly linked in the record, report them separately or leave the weaker one out.
17485
17533
  - If the bank holds nothing that bears on the goal, say so in one line.`;
17486
17534
  }
17535
+ function formatPageFallback(hits) {
17536
+ return "(Hindsight's synthesis was unavailable this turn; these knowledge pages matched the goal by search. Read one with hindsight_read_knowledge_page(<id>) if it looks relevant.)\n" + hits.map((h) => {
17537
+ const snippet = h.snippet.replace(/\s+/g, " ").trim();
17538
+ return `- ${h.name} (${h.id})${snippet ? `: ${snippet}` : ""}`;
17539
+ }).join("\n");
17540
+ }
17541
+ function formatObservationFallback(observations) {
17542
+ return "(Hindsight's synthesis was unavailable this turn; these consolidated observations were recalled from the bank for the goal, unsynthesized.)\n" + observations.map((o) => `- ${o.replace(/\s+/g, " ").trim()}`).join("\n");
17543
+ }
17487
17544
  function buildSystemInjection(memory) {
17488
17545
  return `<hindsight_memory>
17489
17546
  Automatically retrieved by Hindsight from THIS repository's own history (git rationale and past developer sessions) \u2014 real memory, but retrieval is heuristic: it may or may not bear on the current task.
@@ -17541,7 +17598,52 @@ function actionLine(tool, input) {
17541
17598
  var JOURNAL_MAX_BYTES = 8 * 1024 * 1024;
17542
17599
 
17543
17600
  // src/core/hook.ts
17544
- var HOOK_REFLECT_CAP_MS = 25e3;
17601
+ var HOOK_REFLECT_CAP_MS = 2e4;
17602
+ var HOOK_FALLBACK_BUDGET_MS = 7e3;
17603
+ var FALLBACK_PAGE_LIMIT = 3;
17604
+ var FALLBACK_RECALL_MAX_TOKENS = 2e3;
17605
+ async function reflectFallback(harness, prompt, client) {
17606
+ const deadline = Date.now() + HOOK_FALLBACK_BUDGET_MS;
17607
+ const remaining = () => Math.max(deadline - Date.now(), 1);
17608
+ const query = prompt.slice(0, 500);
17609
+ let t0 = Date.now();
17610
+ try {
17611
+ const hits = await client.searchKnowledgePages(query, FALLBACK_PAGE_LIMIT, remaining());
17612
+ diag(harness, "reflect_fallback_pages", { ms: Date.now() - t0, count: hits.length });
17613
+ if (hits.length) {
17614
+ return { memory: formatPageFallback(hits), source: "knowledge_pages", count: hits.length };
17615
+ }
17616
+ } catch (e) {
17617
+ diag(harness, "reflect_fallback_pages_failed", {
17618
+ ms: Date.now() - t0,
17619
+ error: describeError(e)
17620
+ });
17621
+ }
17622
+ t0 = Date.now();
17623
+ try {
17624
+ const observations = await client.recallObservations(prompt.slice(0, 2e3), {
17625
+ maxTokens: FALLBACK_RECALL_MAX_TOKENS,
17626
+ timeoutMs: remaining()
17627
+ });
17628
+ diag(harness, "reflect_fallback_observations", {
17629
+ ms: Date.now() - t0,
17630
+ count: observations.length
17631
+ });
17632
+ if (observations.length) {
17633
+ return {
17634
+ memory: formatObservationFallback(observations),
17635
+ source: "observations",
17636
+ count: observations.length
17637
+ };
17638
+ }
17639
+ } catch (e) {
17640
+ diag(harness, "reflect_fallback_observations_failed", {
17641
+ ms: Date.now() - t0,
17642
+ error: describeError(e)
17643
+ });
17644
+ }
17645
+ return void 0;
17646
+ }
17545
17647
  async function buildHookOutput(args) {
17546
17648
  const { harness, prompt, cfg, client, cacheFile } = args;
17547
17649
  const cached2 = readSessionCache(cacheFile);
@@ -17549,6 +17651,7 @@ async function buildHookOutput(args) {
17549
17651
  let reflectAnswer = cached2.reflectAnswer;
17550
17652
  let reflectRanThisTurn = false;
17551
17653
  let reflectFailed = false;
17654
+ let fallback;
17552
17655
  const deferInitialReflect = cached2.deferInitialReflect === true;
17553
17656
  if (deferInitialReflect) {
17554
17657
  diag(harness, "reflect_deferred_new_bank", { query: prompt.slice(0, 80) });
@@ -17558,7 +17661,7 @@ async function buildHookOutput(args) {
17558
17661
  const timeoutMs = Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS);
17559
17662
  try {
17560
17663
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
17561
- // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
17664
+ // Automatic reflection runs inside a hard 20s slot of the hook window. Hindsight's low budget is the
17562
17665
  // supported default for bounded reflect calls; callers that explicitly invoke the MCP
17563
17666
  // tool still get the deeper high-budget path.
17564
17667
  budget: "low",
@@ -17586,6 +17689,10 @@ async function buildHookOutput(args) {
17586
17689
  error: describeError(e, 1500),
17587
17690
  query: prompt.slice(0, 80)
17588
17691
  });
17692
+ if (e instanceof ReflectError && e.fallbackEligible) {
17693
+ fallback = await reflectFallback(harness, prompt, client);
17694
+ if (fallback) reflectAnswer = fallback.memory;
17695
+ }
17589
17696
  }
17590
17697
  }
17591
17698
  const cadence = cfg.pageRefreshEveryTurns;
@@ -17619,7 +17726,10 @@ async function buildHookOutput(args) {
17619
17726
  }
17620
17727
  const kept = blocks.filter(Boolean);
17621
17728
  let notice;
17622
- if (reflectRanThisTurn && reflectAnswer) {
17729
+ if (fallback) {
17730
+ const what = fallback.source === "knowledge_pages" ? "knowledge page" : "observation";
17731
+ notice = `${brandWord()} \xB7 reflect unavailable \u2014 fell back to ${fallback.count} ${what}${fallback.count === 1 ? "" : "s"} (see ${diagFilePath()})`;
17732
+ } else if (reflectRanThisTurn && reflectAnswer) {
17623
17733
  const q = prompt.replace(/\s+/g, " ").trim();
17624
17734
  const excerpt = q.length > 48 ? `${q.slice(0, 48)}\u2026` : q;
17625
17735
  const preview = reflectAnswer.replace(/\s+/g, " ").trim();
package/dist/grok-hook.js CHANGED
@@ -653,6 +653,22 @@ var KnowledgePagesUnavailableError = class extends Error {
653
653
  }
654
654
  };
655
655
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
656
+ var ReflectError = class extends Error {
657
+ constructor(message, status, timedOut, options) {
658
+ super(message, options);
659
+ this.status = status;
660
+ this.timedOut = timedOut;
661
+ this.name = "ReflectError";
662
+ }
663
+ status;
664
+ timedOut;
665
+ /** A timeout or a 5xx means reflect's synthesis (the slow LLM path) broke, while the cheap
666
+ * retrieval endpoints may still answer — worth falling back. A 4xx will fail the same way on
667
+ * every endpoint (auth, missing bank), so it is not. */
668
+ get fallbackEligible() {
669
+ return this.timedOut || this.status !== void 0 && this.status >= 500;
670
+ }
671
+ };
656
672
  var DEFAULT_MAX_PARALLEL_RETAINS = 10;
657
673
  var POLL_CYCLE_MS = 5e3;
658
674
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
@@ -736,11 +752,11 @@ var HindsightClient = class {
736
752
  return `${this.apiUrl}/v1/default/banks/${encodeURIComponent(this.bank)}${suffix}`;
737
753
  }
738
754
  /** `tolerate` adds statuses that are returned to the caller instead of thrown (404 always is). */
739
- async req(method, url, body, tolerate = []) {
755
+ async req(method, url, body, tolerate = [], timeoutMs = 15e3) {
740
756
  const r = await this.fetchWithAuth(url, {
741
757
  method,
742
758
  body: body ? JSON.stringify(body) : void 0,
743
- signal: AbortSignal.timeout(15e3)
759
+ signal: AbortSignal.timeout(timeoutMs)
744
760
  });
745
761
  if (r.status === 429 && !tolerate.includes(429))
746
762
  throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
@@ -933,7 +949,7 @@ var HindsightClient = class {
933
949
  /**
934
950
  * Reflect: synthesized, root-cause answer over the bank. Bounded so a slow server never hangs a
935
951
  * caller — but `timeoutMs` is REQUIRED, deliberately: the right deadline differs by an order of
936
- * magnitude between the automatic hook (25s, to fit the host's window) and the agent-invoked
952
+ * magnitude between the automatic hook (20s, to fit the host's window) and the agent-invoked
937
953
  * tool (minutes, on a populated bank). This used to default to 120s, which silently overrode the
938
954
  * tool's configured window and aborted every high-budget synthesis mid-flight (#3590).
939
955
  */
@@ -947,19 +963,45 @@ var HindsightClient = class {
947
963
  signal: ctrl.signal
948
964
  });
949
965
  if (!resp.ok)
950
- throw new Error(
951
- `reflect ${resp.status} ${(await resp.text()).slice(0, 1e3)}${this.authHint(resp.status)}`
966
+ throw new ReflectError(
967
+ `reflect ${resp.status} ${(await resp.text()).slice(0, 1e3)}${this.authHint(resp.status)}`,
968
+ resp.status,
969
+ false
952
970
  );
953
971
  const data = await resp.json();
954
972
  return (data.text || "").trim();
955
973
  } catch (e) {
956
974
  if (ctrl.signal.aborted)
957
- throw new Error(`reflect timed out after ${opts.timeoutMs}ms`, { cause: e });
975
+ throw new ReflectError(`reflect timed out after ${opts.timeoutMs}ms`, void 0, true, {
976
+ cause: e
977
+ });
958
978
  throw e;
959
979
  } finally {
960
980
  clearTimeout(timer);
961
981
  }
962
982
  }
983
+ /**
984
+ * Raw recall restricted to consolidated observations — no LLM in the loop, so it still answers
985
+ * when reflect's synthesis times out or 5xxs. Returns the observation texts in rank order.
986
+ */
987
+ async recallObservations(query, opts) {
988
+ const r = await this.req(
989
+ "POST",
990
+ this.bankUrl("/memories/recall"),
991
+ {
992
+ query,
993
+ types: ["observation"],
994
+ budget: "low",
995
+ max_tokens: opts.maxTokens,
996
+ include: { entities: null }
997
+ },
998
+ [],
999
+ opts.timeoutMs
1000
+ );
1001
+ if (r.status === 404) return [];
1002
+ const j = await r.json();
1003
+ return (j.results ?? []).map((x) => (x.text ?? "").trim()).filter(Boolean);
1004
+ }
963
1005
  /**
964
1006
  * The bank's knowledge-base tree (folders + pages, nested). The tree carries names, source
965
1007
  * queries and staleness but NOT synthesized content, so it is cheap enough to poll.
@@ -1024,10 +1066,16 @@ var HindsightClient = class {
1024
1066
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
1025
1067
  * Returns page-level hits with a relevance snippet — the real search behind
1026
1068
  * hindsight_search_knowledge_pages. */
1027
- async searchKnowledgePages(query, limit = 3) {
1069
+ async searchKnowledgePages(query, limit = 3, timeoutMs) {
1028
1070
  if (this.knowledgePagesSupported === false) throw new KnowledgePagesUnavailableError();
1029
1071
  const q = `?q=${encodeURIComponent(query)}&limit=${limit}`;
1030
- const r = await this.req("GET", this.bankUrl(`/knowledge-base/search${q}`));
1072
+ const r = await this.req(
1073
+ "GET",
1074
+ this.bankUrl(`/knowledge-base/search${q}`),
1075
+ void 0,
1076
+ [],
1077
+ timeoutMs
1078
+ );
1031
1079
  const j = await r.json();
1032
1080
  return (j.results ?? []).map((x) => ({
1033
1081
  id: x.id,
@@ -1500,6 +1548,15 @@ Report what this bank's history genuinely bears on that goal. Rendering rules, s
1500
1548
  - Do not connect unrelated episodes into one narrative; if two facts are not explicitly linked in the record, report them separately or leave the weaker one out.
1501
1549
  - If the bank holds nothing that bears on the goal, say so in one line.`;
1502
1550
  }
1551
+ function formatPageFallback(hits) {
1552
+ return "(Hindsight's synthesis was unavailable this turn; these knowledge pages matched the goal by search. Read one with hindsight_read_knowledge_page(<id>) if it looks relevant.)\n" + hits.map((h) => {
1553
+ const snippet = h.snippet.replace(/\s+/g, " ").trim();
1554
+ return `- ${h.name} (${h.id})${snippet ? `: ${snippet}` : ""}`;
1555
+ }).join("\n");
1556
+ }
1557
+ function formatObservationFallback(observations) {
1558
+ return "(Hindsight's synthesis was unavailable this turn; these consolidated observations were recalled from the bank for the goal, unsynthesized.)\n" + observations.map((o) => `- ${o.replace(/\s+/g, " ").trim()}`).join("\n");
1559
+ }
1503
1560
  function buildSystemInjection(memory) {
1504
1561
  return `<hindsight_memory>
1505
1562
  Automatically retrieved by Hindsight from THIS repository's own history (git rationale and past developer sessions) \u2014 real memory, but retrieval is heuristic: it may or may not bear on the current task.
@@ -1695,7 +1752,52 @@ function readJournalTranscript(path) {
1695
1752
  }
1696
1753
 
1697
1754
  // src/core/hook.ts
1698
- var HOOK_REFLECT_CAP_MS = 25e3;
1755
+ var HOOK_REFLECT_CAP_MS = 2e4;
1756
+ var HOOK_FALLBACK_BUDGET_MS = 7e3;
1757
+ var FALLBACK_PAGE_LIMIT = 3;
1758
+ var FALLBACK_RECALL_MAX_TOKENS = 2e3;
1759
+ async function reflectFallback(harness, prompt, client) {
1760
+ const deadline = Date.now() + HOOK_FALLBACK_BUDGET_MS;
1761
+ const remaining = () => Math.max(deadline - Date.now(), 1);
1762
+ const query = prompt.slice(0, 500);
1763
+ let t0 = Date.now();
1764
+ try {
1765
+ const hits = await client.searchKnowledgePages(query, FALLBACK_PAGE_LIMIT, remaining());
1766
+ diag(harness, "reflect_fallback_pages", { ms: Date.now() - t0, count: hits.length });
1767
+ if (hits.length) {
1768
+ return { memory: formatPageFallback(hits), source: "knowledge_pages", count: hits.length };
1769
+ }
1770
+ } catch (e) {
1771
+ diag(harness, "reflect_fallback_pages_failed", {
1772
+ ms: Date.now() - t0,
1773
+ error: describeError(e)
1774
+ });
1775
+ }
1776
+ t0 = Date.now();
1777
+ try {
1778
+ const observations = await client.recallObservations(prompt.slice(0, 2e3), {
1779
+ maxTokens: FALLBACK_RECALL_MAX_TOKENS,
1780
+ timeoutMs: remaining()
1781
+ });
1782
+ diag(harness, "reflect_fallback_observations", {
1783
+ ms: Date.now() - t0,
1784
+ count: observations.length
1785
+ });
1786
+ if (observations.length) {
1787
+ return {
1788
+ memory: formatObservationFallback(observations),
1789
+ source: "observations",
1790
+ count: observations.length
1791
+ };
1792
+ }
1793
+ } catch (e) {
1794
+ diag(harness, "reflect_fallback_observations_failed", {
1795
+ ms: Date.now() - t0,
1796
+ error: describeError(e)
1797
+ });
1798
+ }
1799
+ return void 0;
1800
+ }
1699
1801
  async function buildHookOutput(args) {
1700
1802
  const { harness, prompt, cfg, client, cacheFile } = args;
1701
1803
  const cached = readSessionCache(cacheFile);
@@ -1703,6 +1805,7 @@ async function buildHookOutput(args) {
1703
1805
  let reflectAnswer = cached.reflectAnswer;
1704
1806
  let reflectRanThisTurn = false;
1705
1807
  let reflectFailed = false;
1808
+ let fallback;
1706
1809
  const deferInitialReflect = cached.deferInitialReflect === true;
1707
1810
  if (deferInitialReflect) {
1708
1811
  diag(harness, "reflect_deferred_new_bank", { query: prompt.slice(0, 80) });
@@ -1712,7 +1815,7 @@ async function buildHookOutput(args) {
1712
1815
  const timeoutMs = Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS);
1713
1816
  try {
1714
1817
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
1715
- // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
1818
+ // Automatic reflection runs inside a hard 20s slot of the hook window. Hindsight's low budget is the
1716
1819
  // supported default for bounded reflect calls; callers that explicitly invoke the MCP
1717
1820
  // tool still get the deeper high-budget path.
1718
1821
  budget: "low",
@@ -1740,6 +1843,10 @@ async function buildHookOutput(args) {
1740
1843
  error: describeError(e, 1500),
1741
1844
  query: prompt.slice(0, 80)
1742
1845
  });
1846
+ if (e instanceof ReflectError && e.fallbackEligible) {
1847
+ fallback = await reflectFallback(harness, prompt, client);
1848
+ if (fallback) reflectAnswer = fallback.memory;
1849
+ }
1743
1850
  }
1744
1851
  }
1745
1852
  const cadence = cfg.pageRefreshEveryTurns;
@@ -1773,7 +1880,10 @@ async function buildHookOutput(args) {
1773
1880
  }
1774
1881
  const kept = blocks.filter(Boolean);
1775
1882
  let notice;
1776
- if (reflectRanThisTurn && reflectAnswer) {
1883
+ if (fallback) {
1884
+ const what = fallback.source === "knowledge_pages" ? "knowledge page" : "observation";
1885
+ notice = `${brandWord()} \xB7 reflect unavailable \u2014 fell back to ${fallback.count} ${what}${fallback.count === 1 ? "" : "s"} (see ${diagFilePath()})`;
1886
+ } else if (reflectRanThisTurn && reflectAnswer) {
1777
1887
  const q = prompt.replace(/\s+/g, " ").trim();
1778
1888
  const excerpt = q.length > 48 ? `${q.slice(0, 48)}\u2026` : q;
1779
1889
  const preview = reflectAnswer.replace(/\s+/g, " ").trim();
@@ -661,6 +661,22 @@ var KnowledgePagesUnavailableError = class extends Error {
661
661
  }
662
662
  };
663
663
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
664
+ var ReflectError = class extends Error {
665
+ constructor(message, status, timedOut, options) {
666
+ super(message, options);
667
+ this.status = status;
668
+ this.timedOut = timedOut;
669
+ this.name = "ReflectError";
670
+ }
671
+ status;
672
+ timedOut;
673
+ /** A timeout or a 5xx means reflect's synthesis (the slow LLM path) broke, while the cheap
674
+ * retrieval endpoints may still answer — worth falling back. A 4xx will fail the same way on
675
+ * every endpoint (auth, missing bank), so it is not. */
676
+ get fallbackEligible() {
677
+ return this.timedOut || this.status !== void 0 && this.status >= 500;
678
+ }
679
+ };
664
680
  var DEFAULT_MAX_PARALLEL_RETAINS = 10;
665
681
  var POLL_CYCLE_MS = 5e3;
666
682
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
@@ -744,11 +760,11 @@ var HindsightClient = class {
744
760
  return `${this.apiUrl}/v1/default/banks/${encodeURIComponent(this.bank)}${suffix}`;
745
761
  }
746
762
  /** `tolerate` adds statuses that are returned to the caller instead of thrown (404 always is). */
747
- async req(method, url, body, tolerate = []) {
763
+ async req(method, url, body, tolerate = [], timeoutMs = 15e3) {
748
764
  const r = await this.fetchWithAuth(url, {
749
765
  method,
750
766
  body: body ? JSON.stringify(body) : void 0,
751
- signal: AbortSignal.timeout(15e3)
767
+ signal: AbortSignal.timeout(timeoutMs)
752
768
  });
753
769
  if (r.status === 429 && !tolerate.includes(429))
754
770
  throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
@@ -941,7 +957,7 @@ var HindsightClient = class {
941
957
  /**
942
958
  * Reflect: synthesized, root-cause answer over the bank. Bounded so a slow server never hangs a
943
959
  * caller — but `timeoutMs` is REQUIRED, deliberately: the right deadline differs by an order of
944
- * magnitude between the automatic hook (25s, to fit the host's window) and the agent-invoked
960
+ * magnitude between the automatic hook (20s, to fit the host's window) and the agent-invoked
945
961
  * tool (minutes, on a populated bank). This used to default to 120s, which silently overrode the
946
962
  * tool's configured window and aborted every high-budget synthesis mid-flight (#3590).
947
963
  */
@@ -955,19 +971,45 @@ var HindsightClient = class {
955
971
  signal: ctrl.signal
956
972
  });
957
973
  if (!resp.ok)
958
- throw new Error(
959
- `reflect ${resp.status} ${(await resp.text()).slice(0, 1e3)}${this.authHint(resp.status)}`
974
+ throw new ReflectError(
975
+ `reflect ${resp.status} ${(await resp.text()).slice(0, 1e3)}${this.authHint(resp.status)}`,
976
+ resp.status,
977
+ false
960
978
  );
961
979
  const data = await resp.json();
962
980
  return (data.text || "").trim();
963
981
  } catch (e) {
964
982
  if (ctrl.signal.aborted)
965
- throw new Error(`reflect timed out after ${opts.timeoutMs}ms`, { cause: e });
983
+ throw new ReflectError(`reflect timed out after ${opts.timeoutMs}ms`, void 0, true, {
984
+ cause: e
985
+ });
966
986
  throw e;
967
987
  } finally {
968
988
  clearTimeout(timer);
969
989
  }
970
990
  }
991
+ /**
992
+ * Raw recall restricted to consolidated observations — no LLM in the loop, so it still answers
993
+ * when reflect's synthesis times out or 5xxs. Returns the observation texts in rank order.
994
+ */
995
+ async recallObservations(query, opts) {
996
+ const r = await this.req(
997
+ "POST",
998
+ this.bankUrl("/memories/recall"),
999
+ {
1000
+ query,
1001
+ types: ["observation"],
1002
+ budget: "low",
1003
+ max_tokens: opts.maxTokens,
1004
+ include: { entities: null }
1005
+ },
1006
+ [],
1007
+ opts.timeoutMs
1008
+ );
1009
+ if (r.status === 404) return [];
1010
+ const j = await r.json();
1011
+ return (j.results ?? []).map((x) => (x.text ?? "").trim()).filter(Boolean);
1012
+ }
971
1013
  /**
972
1014
  * The bank's knowledge-base tree (folders + pages, nested). The tree carries names, source
973
1015
  * queries and staleness but NOT synthesized content, so it is cheap enough to poll.
@@ -1032,10 +1074,16 @@ var HindsightClient = class {
1032
1074
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
1033
1075
  * Returns page-level hits with a relevance snippet — the real search behind
1034
1076
  * hindsight_search_knowledge_pages. */
1035
- async searchKnowledgePages(query, limit = 3) {
1077
+ async searchKnowledgePages(query, limit = 3, timeoutMs) {
1036
1078
  if (this.knowledgePagesSupported === false) throw new KnowledgePagesUnavailableError();
1037
1079
  const q = `?q=${encodeURIComponent(query)}&limit=${limit}`;
1038
- const r = await this.req("GET", this.bankUrl(`/knowledge-base/search${q}`));
1080
+ const r = await this.req(
1081
+ "GET",
1082
+ this.bankUrl(`/knowledge-base/search${q}`),
1083
+ void 0,
1084
+ [],
1085
+ timeoutMs
1086
+ );
1039
1087
  const j = await r.json();
1040
1088
  return (j.results ?? []).map((x) => ({
1041
1089
  id: x.id,
@@ -629,6 +629,22 @@ var KnowledgePagesUnavailableError = class extends Error {
629
629
  }
630
630
  };
631
631
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
632
+ var ReflectError = class extends Error {
633
+ constructor(message, status, timedOut, options) {
634
+ super(message, options);
635
+ this.status = status;
636
+ this.timedOut = timedOut;
637
+ this.name = "ReflectError";
638
+ }
639
+ status;
640
+ timedOut;
641
+ /** A timeout or a 5xx means reflect's synthesis (the slow LLM path) broke, while the cheap
642
+ * retrieval endpoints may still answer — worth falling back. A 4xx will fail the same way on
643
+ * every endpoint (auth, missing bank), so it is not. */
644
+ get fallbackEligible() {
645
+ return this.timedOut || this.status !== void 0 && this.status >= 500;
646
+ }
647
+ };
632
648
  var DEFAULT_MAX_PARALLEL_RETAINS = 10;
633
649
  var POLL_CYCLE_MS = 5e3;
634
650
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
@@ -712,11 +728,11 @@ var HindsightClient = class {
712
728
  return `${this.apiUrl}/v1/default/banks/${encodeURIComponent(this.bank)}${suffix}`;
713
729
  }
714
730
  /** `tolerate` adds statuses that are returned to the caller instead of thrown (404 always is). */
715
- async req(method, url, body, tolerate = []) {
731
+ async req(method, url, body, tolerate = [], timeoutMs = 15e3) {
716
732
  const r = await this.fetchWithAuth(url, {
717
733
  method,
718
734
  body: body ? JSON.stringify(body) : void 0,
719
- signal: AbortSignal.timeout(15e3)
735
+ signal: AbortSignal.timeout(timeoutMs)
720
736
  });
721
737
  if (r.status === 429 && !tolerate.includes(429))
722
738
  throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
@@ -909,7 +925,7 @@ var HindsightClient = class {
909
925
  /**
910
926
  * Reflect: synthesized, root-cause answer over the bank. Bounded so a slow server never hangs a
911
927
  * caller — but `timeoutMs` is REQUIRED, deliberately: the right deadline differs by an order of
912
- * magnitude between the automatic hook (25s, to fit the host's window) and the agent-invoked
928
+ * magnitude between the automatic hook (20s, to fit the host's window) and the agent-invoked
913
929
  * tool (minutes, on a populated bank). This used to default to 120s, which silently overrode the
914
930
  * tool's configured window and aborted every high-budget synthesis mid-flight (#3590).
915
931
  */
@@ -923,19 +939,45 @@ var HindsightClient = class {
923
939
  signal: ctrl.signal
924
940
  });
925
941
  if (!resp.ok)
926
- throw new Error(
927
- `reflect ${resp.status} ${(await resp.text()).slice(0, 1e3)}${this.authHint(resp.status)}`
942
+ throw new ReflectError(
943
+ `reflect ${resp.status} ${(await resp.text()).slice(0, 1e3)}${this.authHint(resp.status)}`,
944
+ resp.status,
945
+ false
928
946
  );
929
947
  const data = await resp.json();
930
948
  return (data.text || "").trim();
931
949
  } catch (e) {
932
950
  if (ctrl.signal.aborted)
933
- throw new Error(`reflect timed out after ${opts.timeoutMs}ms`, { cause: e });
951
+ throw new ReflectError(`reflect timed out after ${opts.timeoutMs}ms`, void 0, true, {
952
+ cause: e
953
+ });
934
954
  throw e;
935
955
  } finally {
936
956
  clearTimeout(timer);
937
957
  }
938
958
  }
959
+ /**
960
+ * Raw recall restricted to consolidated observations — no LLM in the loop, so it still answers
961
+ * when reflect's synthesis times out or 5xxs. Returns the observation texts in rank order.
962
+ */
963
+ async recallObservations(query, opts) {
964
+ const r = await this.req(
965
+ "POST",
966
+ this.bankUrl("/memories/recall"),
967
+ {
968
+ query,
969
+ types: ["observation"],
970
+ budget: "low",
971
+ max_tokens: opts.maxTokens,
972
+ include: { entities: null }
973
+ },
974
+ [],
975
+ opts.timeoutMs
976
+ );
977
+ if (r.status === 404) return [];
978
+ const j = await r.json();
979
+ return (j.results ?? []).map((x) => (x.text ?? "").trim()).filter(Boolean);
980
+ }
939
981
  /**
940
982
  * The bank's knowledge-base tree (folders + pages, nested). The tree carries names, source
941
983
  * queries and staleness but NOT synthesized content, so it is cheap enough to poll.
@@ -1000,10 +1042,16 @@ var HindsightClient = class {
1000
1042
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
1001
1043
  * Returns page-level hits with a relevance snippet — the real search behind
1002
1044
  * hindsight_search_knowledge_pages. */
1003
- async searchKnowledgePages(query, limit = 3) {
1045
+ async searchKnowledgePages(query, limit = 3, timeoutMs) {
1004
1046
  if (this.knowledgePagesSupported === false) throw new KnowledgePagesUnavailableError();
1005
1047
  const q = `?q=${encodeURIComponent(query)}&limit=${limit}`;
1006
- const r = await this.req("GET", this.bankUrl(`/knowledge-base/search${q}`));
1048
+ const r = await this.req(
1049
+ "GET",
1050
+ this.bankUrl(`/knowledge-base/search${q}`),
1051
+ void 0,
1052
+ [],
1053
+ timeoutMs
1054
+ );
1007
1055
  const j = await r.json();
1008
1056
  return (j.results ?? []).map((x) => ({
1009
1057
  id: x.id,