@vectorize-io/hindsight-coding-agents 0.6.1 → 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.
- package/README.md +179 -40
- package/dist/antigravity-hook.js +343 -158
- package/dist/antigravity-statusline.js +117 -4
- package/dist/antigravity-stop-hook.js +262 -113
- package/dist/claude-hook.js +343 -158
- package/dist/claude-sessionstart-hook.js +348 -136
- package/dist/claude-stop-hook.js +262 -113
- package/dist/cline.js +493 -173
- package/dist/codex-hook.js +343 -158
- package/dist/codex-sessionstart-hook.js +348 -136
- package/dist/codex-stop-hook.js +262 -113
- package/dist/copilot-hook.js +343 -158
- package/dist/copilot-sessionstart-hook.js +348 -136
- package/dist/copilot-stop-hook.js +262 -113
- package/dist/cursor-hook.js +343 -158
- package/dist/cursor-sessionstart-hook.js +348 -136
- package/dist/cursor-stop-hook.js +262 -113
- package/dist/daemon-start.js +116 -4
- package/dist/dcode-hook.js +343 -158
- package/dist/dcode-sessionstart-hook.js +348 -136
- package/dist/dcode-stop-hook.js +262 -113
- package/dist/deepen.js +204 -47
- package/dist/devin-hook.js +343 -158
- package/dist/devin-sessionstart-hook.js +348 -136
- package/dist/devin-stop-hook.js +262 -113
- package/dist/droid-hook.js +343 -158
- package/dist/droid-sessionstart-hook.js +348 -136
- package/dist/droid-stop-hook.js +262 -113
- package/dist/dsh.js +493 -173
- package/dist/grok-hook.js +343 -158
- package/dist/grok-sessionstart-hook.js +348 -136
- package/dist/grok-stop-hook.js +262 -113
- package/dist/hindsight-seed.js +116 -4
- package/dist/index.js +493 -173
- package/dist/installer.js +92 -70
- package/dist/kilo.js +493 -173
- package/dist/mcp-server.js +230 -57
- package/dist/opencode2.js +520 -173
- package/dist/pi.js +494 -175
- package/dist/prime-agent.js +494 -175
- package/dist/qwen-hook.js +343 -158
- package/dist/qwen-sessionstart-hook.js +348 -136
- package/dist/qwen-stop-hook.js +262 -113
- package/dist/status.js +203 -47
- package/dist/zcode-hook.js +343 -158
- package/dist/zcode-sessionstart-hook.js +348 -136
- package/dist/zcode-stop-hook.js +262 -113
- package/package.json +2 -2
- package/plugin.json +1 -1
- package/skill/SKILL.md +173 -39
package/dist/mcp-server.js
CHANGED
|
@@ -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:
|
|
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:
|
|
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:
|
|
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.
|
|
31635
|
-
//
|
|
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:
|
|
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
|
-
|
|
31713
|
+
var PAGE_NAMES = PAGE_TAXONOMY.map((page) => page.name);
|
|
31714
|
+
function pagesFor(project, pages = {}, customPages = {}) {
|
|
31712
31715
|
const scope = pageScopeRule(project);
|
|
31713
|
-
|
|
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:
|
|
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 =
|
|
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
|
|
31826
|
-
|
|
31827
|
-
|
|
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
|
|
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(
|
|
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
|
|
32229
|
-
*
|
|
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
|
-
|
|
32237
|
-
|
|
32238
|
-
|
|
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 (
|
|
32257
|
-
|
|
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,
|
|
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 (
|
|
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 (
|
|
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 (
|
|
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 ||
|
|
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
|
-
|
|
32593
|
-
|
|
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:
|
|
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
|
|
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
|
-
|
|
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
|
|
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,
|