@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.
- package/README.md +5 -2
- package/dist/antigravity-hook.js +121 -11
- package/dist/antigravity-stop-hook.js +56 -8
- package/dist/claude-hook.js +121 -11
- package/dist/claude-sessionstart-hook.js +56 -8
- package/dist/claude-stop-hook.js +56 -8
- package/dist/cline.js +121 -11
- package/dist/codex-hook.js +121 -11
- package/dist/codex-sessionstart-hook.js +56 -8
- package/dist/codex-stop-hook.js +56 -8
- package/dist/copilot-hook.js +121 -11
- package/dist/copilot-sessionstart-hook.js +56 -8
- package/dist/copilot-stop-hook.js +56 -8
- package/dist/cursor-hook.js +121 -11
- package/dist/cursor-sessionstart-hook.js +56 -8
- package/dist/cursor-stop-hook.js +56 -8
- package/dist/dcode-hook.js +121 -11
- package/dist/dcode-sessionstart-hook.js +56 -8
- package/dist/dcode-stop-hook.js +56 -8
- package/dist/deepen.js +56 -8
- package/dist/devin-hook.js +121 -11
- package/dist/devin-sessionstart-hook.js +56 -8
- package/dist/devin-stop-hook.js +56 -8
- package/dist/droid-hook.js +121 -11
- package/dist/droid-sessionstart-hook.js +56 -8
- package/dist/droid-stop-hook.js +56 -8
- package/dist/dsh.js +121 -11
- package/dist/grok-hook.js +121 -11
- package/dist/grok-sessionstart-hook.js +56 -8
- package/dist/grok-stop-hook.js +56 -8
- package/dist/index.js +121 -11
- package/dist/kilo.js +121 -11
- package/dist/mcp-server.js +56 -8
- package/dist/opencode2.js +121 -11
- package/dist/pi.js +121 -11
- package/dist/prime-agent.js +121 -11
- package/dist/qwen-hook.js +121 -11
- package/dist/qwen-sessionstart-hook.js +56 -8
- package/dist/qwen-stop-hook.js +56 -8
- package/dist/status.js +56 -8
- package/dist/zcode-hook.js +121 -11
- package/dist/zcode-sessionstart-hook.js +56 -8
- package/dist/zcode-stop-hook.js +56 -8
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skill/SKILL.md +5 -2
package/README.md
CHANGED
|
@@ -522,7 +522,7 @@ hook by Codex...), so one shared config serves several agents side by side:
|
|
|
522
522
|
| `manageBankConfig` | `true` | let the plugin shape the bank's own configuration — the retain strategies it writes under, the `knowledge` entity-label group, and, on a bank that has none, the missions. Writing is strictly **additive**: it adds what the bank does not define and never overwrites what is there, so your control-plane edits survive. Set `false` to keep it out of the bank config entirely — see **A bank you shape yourself** below |
|
|
523
523
|
| `observationScopes` | `"shared"` | how consolidation groups observations: `"shared"` (default) = ONE global scope per bank, so every agent on a repo builds one set of beliefs; also `"combined"` (the server default), `"per_tag"`, `"all_combinations"`, `[["t"]]`; `"per_source"` adds a scope per `source:` kind alongside the global one, so commit knowledge and conversation knowledge consolidate apart |
|
|
524
524
|
| `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
|
|
525
|
-
| `reflectTimeoutMs` | `120000` | **automatic** session-reflect timeout (hook harnesses additionally cap it at
|
|
525
|
+
| `reflectTimeoutMs` | `120000` | **automatic** session-reflect timeout (hook harnesses additionally cap it at 20s to fit the host's hook window); on timeout or a 5xx the hook falls back to knowledge-page search, then to a raw recall of observations (recorded) |
|
|
526
526
|
| `reflectToolTimeoutMs` | `330000` | timeout for the agent-invoked `hindsight_reflect` tool — a call the agent waits on, whose high-budget synthesis on a populated bank runs for minutes. Defaults above the server's own reflect wall timeout (`HINDSIGHT_API_REFLECT_WALL_TIMEOUT`, 300s) so the server decides when to give up. Unset, it inherits an explicitly raised `reflectTimeoutMs`, but a short one never lowers it |
|
|
527
527
|
| `reflectBudget` | `"high"` | reflect budget for the `hindsight_reflect` tool: `"low"`, `"mid"` or `"high"`. Drop it on a large bank where high-budget synthesis exceeds the server's wall timeout. The automatic session-start reflect always uses `"low"` to fit its hook window and is unaffected |
|
|
528
528
|
| `autoReflect` | `true` | inject a one-time reflect synthesis on the session's **first prompt**. `false` = tool-only reflect: nothing is injected; the agent searches knowledge pages first and reflects only when they are too shallow |
|
|
@@ -845,7 +845,10 @@ as a JSON line to `/tmp/hindsight-plugin.log` (override with `HINDSIGHT_DIAG_FIL
|
|
|
845
845
|
```
|
|
846
846
|
|
|
847
847
|
`reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
|
|
848
|
-
check this file — a run whose reflects failed is a no-memory run.
|
|
848
|
+
check this file — a run whose reflects failed is a no-memory run. When the failure was a timeout or
|
|
849
|
+
a 5xx, the hook falls back to knowledge-page search and, if no page matches, to a raw recall of the
|
|
850
|
+
bank's observations: `reflect_fallback_pages` / `reflect_fallback_observations` record what each
|
|
851
|
+
step returned (`*_failed` when it errored). Seed starts are logged as
|
|
849
852
|
`seed_started`.
|
|
850
853
|
|
|
851
854
|
### Is the memory ready yet?
|
package/dist/antigravity-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(
|
|
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 (
|
|
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
|
|
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
|
|
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(
|
|
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 =
|
|
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
|
|
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 (
|
|
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();
|
|
@@ -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(
|
|
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 (
|
|
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
|
|
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
|
|
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(
|
|
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,
|
package/dist/claude-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(
|
|
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 (
|
|
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
|
|
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
|
|
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(
|
|
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 =
|
|
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
|
|
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 (
|
|
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();
|