@vectorize-io/hindsight-coding-agents 0.1.2 → 0.2.1
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 +30 -3
- package/dist/antigravity-hook.js +73 -15
- package/dist/antigravity-statusline.js +32 -12
- package/dist/antigravity-stop-hook.js +144 -21
- package/dist/claude-hook.js +73 -15
- package/dist/claude-sessionstart-hook.js +73 -15
- package/dist/claude-stop-hook.js +144 -21
- package/dist/cline.js +141 -21
- package/dist/codex-hook.js +73 -15
- package/dist/codex-sessionstart-hook.js +73 -15
- package/dist/codex-stop-hook.js +144 -21
- package/dist/copilot-hook.js +73 -15
- package/dist/copilot-sessionstart-hook.js +73 -15
- package/dist/copilot-stop-hook.js +144 -21
- package/dist/cursor-hook.js +73 -15
- package/dist/cursor-sessionstart-hook.js +73 -15
- package/dist/cursor-stop-hook.js +144 -21
- package/dist/daemon-start.js +14 -1
- package/dist/deepen.js +69 -14
- package/dist/devin-hook.js +73 -15
- package/dist/devin-sessionstart-hook.js +73 -15
- package/dist/devin-stop-hook.js +144 -21
- package/dist/grok-hook.js +73 -15
- package/dist/grok-sessionstart-hook.js +73 -15
- package/dist/grok-stop-hook.js +144 -21
- package/dist/hindsight-seed.js +32 -12
- package/dist/index.js +142 -22
- package/dist/installer.js +5 -1
- package/dist/kilo.js +142 -22
- package/dist/mcp-server.js +70 -15
- package/dist/status.js +69 -14
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -263,8 +263,10 @@ Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering,
|
|
|
263
263
|
4. its `harnesses.<name>` section — per-agent override
|
|
264
264
|
|
|
265
265
|
Environment variables are a **fallback**: the file wins wherever it sets a value, so adding env to
|
|
266
|
-
an existing setup changes nothing.
|
|
267
|
-
|
|
266
|
+
an existing setup changes nothing. `retainTags` takes a comma-separated list
|
|
267
|
+
(`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are trimmed and blanks dropped.
|
|
268
|
+
The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`) are file-only —
|
|
269
|
+
per-key branching doesn't survive flattening into one variable.
|
|
268
270
|
|
|
269
271
|
There is deliberately no repo-carried config file — per-repo bank routing is `mapPathToBank`,
|
|
270
272
|
per-agent differences are `harnesses.<name>`.
|
|
@@ -293,6 +295,8 @@ hook by Codex...), so one shared config serves several agents side by side:
|
|
|
293
295
|
| `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
|
|
294
296
|
| `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; overrides everything |
|
|
295
297
|
| `resolveWorktrees` | `true` | `{gitProject}`: linked worktrees share the main repo's bank |
|
|
298
|
+
| `retainTags` | — | extra tags on every session write-back, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
|
|
299
|
+
| `retainMetadata` | — | extra metadata on every session write-back, e.g. `{"repo": "{gitProject}"}` |
|
|
296
300
|
| `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
|
|
297
301
|
| `reflectTimeoutMs` | `120000` | session-reflect timeout (hook harnesses additionally cap it at 25s to fit the host's hook window); on timeout the session runs without reflect (recorded) |
|
|
298
302
|
| `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
|
|
@@ -302,7 +306,7 @@ hook by Codex...), so one shared config serves several agents side by side:
|
|
|
302
306
|
| `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
|
|
303
307
|
| `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
|
|
304
308
|
| `retainSessions` | `true` | plugin-harness write-back (opencode, Kilo): async upsert of the session transcript every turn, plus an idle flush that captures the reply the per-turn pass can't see (set `false` to opt out; hook harnesses always write on Stop) |
|
|
305
|
-
| `retainEveryTurns` | `1` |
|
|
309
|
+
| `retainEveryTurns` | `1` | write-back cadence in user turns, for the plugin harnesses (opencode, Kilo, Cline CLI) — hook harnesses write on every Stop and ignore it |
|
|
306
310
|
| `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
|
|
307
311
|
| `gitIngest` | `"message"` | git depth for seeding AND staying current (same engine): `"message"` = commit messages only (one doc, re-upserted when HEAD moves); `"full"` = messages + per-commit full diffs (progressive, newest first); `"none"` = git off |
|
|
308
312
|
| `harnesses.<name>` | — | per-harness override of any field above |
|
|
@@ -375,6 +379,29 @@ Coding memory is **per repository**. Resolution order for the working directory:
|
|
|
375
379
|
The default `"coding-agent::{gitProject}"` is **harness-neutral**, so opencode, Claude Code, and Codex
|
|
376
380
|
all share one memory per repo — use `"{harness}-{gitProject}"` to split per agent instead.
|
|
377
381
|
|
|
382
|
+
### Recording where a memory came from
|
|
383
|
+
|
|
384
|
+
With a bank per repo, the bank _is_ the answer to "where did this come from". On a deliberately
|
|
385
|
+
**shared** bank — one bank holding cross-project knowledge so facts recall everywhere — it isn't:
|
|
386
|
+
every memory looks alike. `retainTags` and `retainMetadata` stamp that provenance onto each session
|
|
387
|
+
write-back:
|
|
388
|
+
|
|
389
|
+
```jsonc
|
|
390
|
+
{
|
|
391
|
+
"bankId": "shared", // one bank for everything
|
|
392
|
+
"retainTags": ["project:{gitProject}", "env:work"],
|
|
393
|
+
"retainMetadata": { "repo": "{gitProject}" },
|
|
394
|
+
}
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Recalls can then filter by `project:<repo>`, and every document shows which repository it came out
|
|
398
|
+
of. Both accept the same placeholders as `bankIdTemplate` — `{gitProject}`, `{project}`,
|
|
399
|
+
`{harness}`, `{channel}`, `{user}` — plus `{bankId}`, `{sessionId}` and `{timestamp}`.
|
|
400
|
+
`{gitProject}` is worktree-aware here too, so every linked worktree of a repo stamps one name.
|
|
401
|
+
|
|
402
|
+
The plugin's own `source:` and `harness:` tags are reserved: entries in those namespaces are ignored
|
|
403
|
+
with a warning, so a document's agent attribution always reflects the agent that actually wrote it.
|
|
404
|
+
|
|
378
405
|
## Ingestion internals (no CLI)
|
|
379
406
|
|
|
380
407
|
There is no user-facing ingest command — the deepen engine (`dist/deepen.js`) is spawned by every
|
package/dist/antigravity-hook.js
CHANGED
|
@@ -7,9 +7,25 @@ import { existsSync, readFileSync as readFileSync3 } from "fs";
|
|
|
7
7
|
import { execFileSync } from "child_process";
|
|
8
8
|
import { homedir } from "os";
|
|
9
9
|
import { basename, dirname, join, normalize, sep } from "path";
|
|
10
|
+
|
|
11
|
+
// src/core/template.ts
|
|
12
|
+
var PLACEHOLDER = /\{([a-zA-Z_]+)\}/g;
|
|
13
|
+
function applyTemplate(template, resolvers, what) {
|
|
14
|
+
return template.replace(PLACEHOLDER, (_, name) => {
|
|
15
|
+
const resolve2 = resolvers[name];
|
|
16
|
+
if (!resolve2) {
|
|
17
|
+
console.error(
|
|
18
|
+
`hindsight: unknown ${what} placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
|
|
19
|
+
);
|
|
20
|
+
return "unknown";
|
|
21
|
+
}
|
|
22
|
+
return resolve2();
|
|
23
|
+
});
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
// src/core/bank.ts
|
|
10
27
|
var DEFAULT_BANK_NAME = "coding";
|
|
11
28
|
var DEFAULT_TEMPLATE = "coding-agent::{gitProject}";
|
|
12
|
-
var PLACEHOLDER = /\{([a-zA-Z]+)\}/g;
|
|
13
29
|
function getProjectRootFromGit(directory) {
|
|
14
30
|
if (!directory) return null;
|
|
15
31
|
try {
|
|
@@ -55,16 +71,7 @@ function deriveBankId(config, directory, harness = "coding") {
|
|
|
55
71
|
channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
|
|
56
72
|
user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
|
|
57
73
|
};
|
|
58
|
-
return (config.bankIdTemplate || DEFAULT_TEMPLATE
|
|
59
|
-
const r = resolvers[name];
|
|
60
|
-
if (!r) {
|
|
61
|
-
console.error(
|
|
62
|
-
`hindsight: unknown bankIdTemplate placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
|
|
63
|
-
);
|
|
64
|
-
return "unknown";
|
|
65
|
-
}
|
|
66
|
-
return r();
|
|
67
|
-
});
|
|
74
|
+
return applyTemplate(config.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
|
|
68
75
|
}
|
|
69
76
|
|
|
70
77
|
// src/core/config.ts
|
|
@@ -144,6 +151,12 @@ function resolveConfig(raw = {}) {
|
|
|
144
151
|
surveyBudgetUsd: raw.surveyBudgetUsd || 2,
|
|
145
152
|
surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
|
|
146
153
|
gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
|
|
154
|
+
// Hostile input is a config typo, not an attack: keep only string entries so a stray number or
|
|
155
|
+
// nested object cannot reach the API as a tag and fail the whole retain.
|
|
156
|
+
retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
|
|
157
|
+
retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
|
|
158
|
+
Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
|
|
159
|
+
) : {},
|
|
147
160
|
banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
|
|
148
161
|
logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
|
|
149
162
|
};
|
|
@@ -197,7 +210,10 @@ var ENV_KEYS = {
|
|
|
197
210
|
surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
|
|
198
211
|
surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
|
|
199
212
|
logLevel: "HINDSIGHT_LOG_LEVEL",
|
|
200
|
-
gitIngest: "HINDSIGHT_GIT_INGEST"
|
|
213
|
+
gitIngest: "HINDSIGHT_GIT_INGEST",
|
|
214
|
+
// Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
|
|
215
|
+
// a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
|
|
216
|
+
retainTags: "HINDSIGHT_RETAIN_TAGS"
|
|
201
217
|
};
|
|
202
218
|
var ENV_BOOLEANS = /* @__PURE__ */ new Set([
|
|
203
219
|
"dynamicBankId",
|
|
@@ -208,6 +224,7 @@ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
|
|
|
208
224
|
"autoSeed",
|
|
209
225
|
"codebaseSurvey"
|
|
210
226
|
]);
|
|
227
|
+
var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
|
|
211
228
|
var ENV_NUMBERS = /* @__PURE__ */ new Set([
|
|
212
229
|
"apiPort",
|
|
213
230
|
"daemonIdleTimeout",
|
|
@@ -225,6 +242,9 @@ function readEnvConfig(env = process.env) {
|
|
|
225
242
|
if (value === void 0 || value.trim() === "") continue;
|
|
226
243
|
if (ENV_BOOLEANS.has(key)) {
|
|
227
244
|
out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
|
|
245
|
+
} else if (ENV_LISTS.has(key)) {
|
|
246
|
+
const items = value.split(",").map((v) => v.trim()).filter(Boolean);
|
|
247
|
+
if (items.length) out[key] = items;
|
|
228
248
|
} else if (ENV_NUMBERS.has(key)) {
|
|
229
249
|
const n = Number(value);
|
|
230
250
|
if (Number.isFinite(n)) out[key] = n;
|
|
@@ -439,6 +459,13 @@ var CODING_BANK_TEMPLATE = {
|
|
|
439
459
|
entities_allow_free_form: true
|
|
440
460
|
}
|
|
441
461
|
};
|
|
462
|
+
var CODING_BANK_STRUCTURE = {
|
|
463
|
+
version: "1",
|
|
464
|
+
bank: {
|
|
465
|
+
retain_strategies: RETAIN_STRATEGIES,
|
|
466
|
+
entity_labels: [KNOWLEDGE_LABELS]
|
|
467
|
+
}
|
|
468
|
+
};
|
|
442
469
|
|
|
443
470
|
// src/core/util.ts
|
|
444
471
|
var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
@@ -466,6 +493,7 @@ var KnowledgePagesUnavailableError = class extends Error {
|
|
|
466
493
|
}
|
|
467
494
|
};
|
|
468
495
|
var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
|
|
496
|
+
var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
|
|
469
497
|
var HindsightClient = class {
|
|
470
498
|
apiUrl;
|
|
471
499
|
apiToken;
|
|
@@ -582,12 +610,39 @@ var HindsightClient = class {
|
|
|
582
610
|
await this.req("DELETE", this.bankUrl());
|
|
583
611
|
this.log(`[bank] reset ${this.bank}`);
|
|
584
612
|
}
|
|
585
|
-
|
|
613
|
+
const seeded = opts.reset ? false : await this.hasBankMissions();
|
|
614
|
+
await this.req(
|
|
615
|
+
"POST",
|
|
616
|
+
this.bankUrl("/import"),
|
|
617
|
+
seeded ? CODING_BANK_STRUCTURE : CODING_BANK_TEMPLATE
|
|
618
|
+
);
|
|
586
619
|
this.log(
|
|
587
|
-
`[bank] template applied to ${this.bank}: missions, entity_labels {knowledge}, strategies {git, gitlog, conversation, document}`
|
|
620
|
+
seeded ? `[bank] structure applied to ${this.bank}: entity_labels {knowledge}, strategies {git, gitlog, conversation, document} \u2014 missions left as configured` : `[bank] template applied to ${this.bank}: missions, entity_labels {knowledge}, strategies {git, gitlog, conversation, document}`
|
|
588
621
|
);
|
|
589
622
|
await this.seedPages();
|
|
590
623
|
}
|
|
624
|
+
/**
|
|
625
|
+
* Whether this bank already carries bank-level mission overrides — ours from an earlier seed, or
|
|
626
|
+
* the user's own edit. Either way they are not ours to overwrite.
|
|
627
|
+
*
|
|
628
|
+
* Reads the bank-scoped OVERRIDES, not the resolved config, so inherited global defaults don't
|
|
629
|
+
* read as "already set". A missing bank, or a deployment with the bank-config API switched off,
|
|
630
|
+
* answers false: there is nothing to preserve, and without that API a user cannot set per-bank
|
|
631
|
+
* missions in the first place.
|
|
632
|
+
*/
|
|
633
|
+
async hasBankMissions() {
|
|
634
|
+
try {
|
|
635
|
+
const r = await this.req("GET", this.bankUrl("/config"));
|
|
636
|
+
if (!r.ok) return false;
|
|
637
|
+
const j = await r.json();
|
|
638
|
+
return MISSION_FIELDS.some((f) => {
|
|
639
|
+
const v = j.overrides?.[f];
|
|
640
|
+
return typeof v === "string" && v.trim() !== "";
|
|
641
|
+
});
|
|
642
|
+
} catch {
|
|
643
|
+
return false;
|
|
644
|
+
}
|
|
645
|
+
}
|
|
591
646
|
/** Delete one document (cascades its memory units/links). Used by deepen's self-cleanup. */
|
|
592
647
|
async deleteDocument(documentId) {
|
|
593
648
|
await this.req("DELETE", this.bankUrl(`/documents/${encodeURIComponent(documentId)}`));
|
|
@@ -1086,6 +1141,9 @@ import { execFileSync as execFileSync2, spawn as realSpawn2 } from "child_proces
|
|
|
1086
1141
|
import { dirname as dirname5, join as join6 } from "path";
|
|
1087
1142
|
import { fileURLToPath as fileURLToPath2 } from "url";
|
|
1088
1143
|
|
|
1144
|
+
// src/core/retain-stamp.ts
|
|
1145
|
+
import { basename as basename2 } from "path";
|
|
1146
|
+
|
|
1089
1147
|
// src/core/jsonl.ts
|
|
1090
1148
|
import { closeSync, openSync, readSync, statSync } from "fs";
|
|
1091
1149
|
import { StringDecoder } from "string_decoder";
|
|
@@ -1148,7 +1206,7 @@ function* streamLines(path, start) {
|
|
|
1148
1206
|
}
|
|
1149
1207
|
|
|
1150
1208
|
// src/core/transcript-util.ts
|
|
1151
|
-
var MEMORY_TAG_RE = /<(hook_prompt|hindsight_memory|hindsight_memories|hindsight_bank|relevant_memories|user_feedback|hindsight_knowledge|hindsight_knowledge_refresh)\b[\s\S]*?<\/\1>/g;
|
|
1209
|
+
var MEMORY_TAG_RE = /<(hook_prompt|task-notification|system-reminder|hindsight_memory|hindsight_memories|hindsight_bank|relevant_memories|user_feedback|hindsight_knowledge|hindsight_knowledge_refresh)\b[\s\S]*?<\/\1>/g;
|
|
1152
1210
|
function stripInjectedMemory(s) {
|
|
1153
1211
|
return s.replace(MEMORY_TAG_RE, "");
|
|
1154
1212
|
}
|
|
@@ -51,6 +51,12 @@ function resolveConfig(raw = {}) {
|
|
|
51
51
|
surveyBudgetUsd: raw.surveyBudgetUsd || 2,
|
|
52
52
|
surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
|
|
53
53
|
gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
|
|
54
|
+
// Hostile input is a config typo, not an attack: keep only string entries so a stray number or
|
|
55
|
+
// nested object cannot reach the API as a tag and fail the whole retain.
|
|
56
|
+
retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
|
|
57
|
+
retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
|
|
58
|
+
Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
|
|
59
|
+
) : {},
|
|
54
60
|
banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
|
|
55
61
|
logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
|
|
56
62
|
};
|
|
@@ -104,7 +110,10 @@ var ENV_KEYS = {
|
|
|
104
110
|
surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
|
|
105
111
|
surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
|
|
106
112
|
logLevel: "HINDSIGHT_LOG_LEVEL",
|
|
107
|
-
gitIngest: "HINDSIGHT_GIT_INGEST"
|
|
113
|
+
gitIngest: "HINDSIGHT_GIT_INGEST",
|
|
114
|
+
// Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
|
|
115
|
+
// a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
|
|
116
|
+
retainTags: "HINDSIGHT_RETAIN_TAGS"
|
|
108
117
|
};
|
|
109
118
|
var ENV_BOOLEANS = /* @__PURE__ */ new Set([
|
|
110
119
|
"dynamicBankId",
|
|
@@ -115,6 +124,7 @@ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
|
|
|
115
124
|
"autoSeed",
|
|
116
125
|
"codebaseSurvey"
|
|
117
126
|
]);
|
|
127
|
+
var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
|
|
118
128
|
var ENV_NUMBERS = /* @__PURE__ */ new Set([
|
|
119
129
|
"apiPort",
|
|
120
130
|
"daemonIdleTimeout",
|
|
@@ -132,6 +142,9 @@ function readEnvConfig(env = process.env) {
|
|
|
132
142
|
if (value === void 0 || value.trim() === "") continue;
|
|
133
143
|
if (ENV_BOOLEANS.has(key)) {
|
|
134
144
|
out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
|
|
145
|
+
} else if (ENV_LISTS.has(key)) {
|
|
146
|
+
const items = value.split(",").map((v) => v.trim()).filter(Boolean);
|
|
147
|
+
if (items.length) out[key] = items;
|
|
135
148
|
} else if (ENV_NUMBERS.has(key)) {
|
|
136
149
|
const n = Number(value);
|
|
137
150
|
if (Number.isFinite(n)) out[key] = n;
|
|
@@ -181,9 +194,25 @@ function resolvePartial(cfg, patch) {
|
|
|
181
194
|
import { execFileSync } from "child_process";
|
|
182
195
|
import { homedir as homedir2 } from "os";
|
|
183
196
|
import { basename, dirname as dirname2, join as join3, normalize, sep } from "path";
|
|
197
|
+
|
|
198
|
+
// src/core/template.ts
|
|
199
|
+
var PLACEHOLDER = /\{([a-zA-Z_]+)\}/g;
|
|
200
|
+
function applyTemplate(template, resolvers, what) {
|
|
201
|
+
return template.replace(PLACEHOLDER, (_, name) => {
|
|
202
|
+
const resolve = resolvers[name];
|
|
203
|
+
if (!resolve) {
|
|
204
|
+
console.error(
|
|
205
|
+
`hindsight: unknown ${what} placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
|
|
206
|
+
);
|
|
207
|
+
return "unknown";
|
|
208
|
+
}
|
|
209
|
+
return resolve();
|
|
210
|
+
});
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
// src/core/bank.ts
|
|
184
214
|
var DEFAULT_BANK_NAME = "coding";
|
|
185
215
|
var DEFAULT_TEMPLATE = "coding-agent::{gitProject}";
|
|
186
|
-
var PLACEHOLDER = /\{([a-zA-Z]+)\}/g;
|
|
187
216
|
function getProjectRootFromGit(directory) {
|
|
188
217
|
if (!directory) return null;
|
|
189
218
|
try {
|
|
@@ -229,16 +258,7 @@ function deriveBankId(config, directory, harness = "coding") {
|
|
|
229
258
|
channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
|
|
230
259
|
user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
|
|
231
260
|
};
|
|
232
|
-
return (config.bankIdTemplate || DEFAULT_TEMPLATE
|
|
233
|
-
const r = resolvers[name];
|
|
234
|
-
if (!r) {
|
|
235
|
-
console.error(
|
|
236
|
-
`hindsight: unknown bankIdTemplate placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
|
|
237
|
-
);
|
|
238
|
-
return "unknown";
|
|
239
|
-
}
|
|
240
|
-
return r();
|
|
241
|
-
});
|
|
261
|
+
return applyTemplate(config.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
|
|
242
262
|
}
|
|
243
263
|
|
|
244
264
|
// src/core/brand.ts
|
|
@@ -7,9 +7,25 @@ import { existsSync, readFileSync as readFileSync3 } from "fs";
|
|
|
7
7
|
import { execFileSync } from "child_process";
|
|
8
8
|
import { homedir } from "os";
|
|
9
9
|
import { basename, dirname, join, normalize, sep } from "path";
|
|
10
|
+
|
|
11
|
+
// src/core/template.ts
|
|
12
|
+
var PLACEHOLDER = /\{([a-zA-Z_]+)\}/g;
|
|
13
|
+
function applyTemplate(template, resolvers, what) {
|
|
14
|
+
return template.replace(PLACEHOLDER, (_, name) => {
|
|
15
|
+
const resolve2 = resolvers[name];
|
|
16
|
+
if (!resolve2) {
|
|
17
|
+
console.error(
|
|
18
|
+
`hindsight: unknown ${what} placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
|
|
19
|
+
);
|
|
20
|
+
return "unknown";
|
|
21
|
+
}
|
|
22
|
+
return resolve2();
|
|
23
|
+
});
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
// src/core/bank.ts
|
|
10
27
|
var DEFAULT_BANK_NAME = "coding";
|
|
11
28
|
var DEFAULT_TEMPLATE = "coding-agent::{gitProject}";
|
|
12
|
-
var PLACEHOLDER = /\{([a-zA-Z]+)\}/g;
|
|
13
29
|
function getProjectRootFromGit(directory) {
|
|
14
30
|
if (!directory) return null;
|
|
15
31
|
try {
|
|
@@ -24,6 +40,9 @@ function getProjectRootFromGit(directory) {
|
|
|
24
40
|
return null;
|
|
25
41
|
}
|
|
26
42
|
}
|
|
43
|
+
function projectNameOf(directory) {
|
|
44
|
+
return gitProjectName(directory, true);
|
|
45
|
+
}
|
|
27
46
|
function gitProjectName(directory, resolveWorktrees) {
|
|
28
47
|
if (resolveWorktrees) {
|
|
29
48
|
const root = getProjectRootFromGit(directory);
|
|
@@ -55,16 +74,7 @@ function deriveBankId(config, directory, harness = "coding") {
|
|
|
55
74
|
channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
|
|
56
75
|
user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
|
|
57
76
|
};
|
|
58
|
-
return (config.bankIdTemplate || DEFAULT_TEMPLATE
|
|
59
|
-
const r = resolvers[name];
|
|
60
|
-
if (!r) {
|
|
61
|
-
console.error(
|
|
62
|
-
`hindsight: unknown bankIdTemplate placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
|
|
63
|
-
);
|
|
64
|
-
return "unknown";
|
|
65
|
-
}
|
|
66
|
-
return r();
|
|
67
|
-
});
|
|
77
|
+
return applyTemplate(config.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
|
|
68
78
|
}
|
|
69
79
|
|
|
70
80
|
// src/core/config.ts
|
|
@@ -118,6 +128,12 @@ function resolveConfig(raw = {}) {
|
|
|
118
128
|
surveyBudgetUsd: raw.surveyBudgetUsd || 2,
|
|
119
129
|
surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
|
|
120
130
|
gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
|
|
131
|
+
// Hostile input is a config typo, not an attack: keep only string entries so a stray number or
|
|
132
|
+
// nested object cannot reach the API as a tag and fail the whole retain.
|
|
133
|
+
retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
|
|
134
|
+
retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
|
|
135
|
+
Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
|
|
136
|
+
) : {},
|
|
121
137
|
banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
|
|
122
138
|
logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
|
|
123
139
|
};
|
|
@@ -171,7 +187,10 @@ var ENV_KEYS = {
|
|
|
171
187
|
surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
|
|
172
188
|
surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
|
|
173
189
|
logLevel: "HINDSIGHT_LOG_LEVEL",
|
|
174
|
-
gitIngest: "HINDSIGHT_GIT_INGEST"
|
|
190
|
+
gitIngest: "HINDSIGHT_GIT_INGEST",
|
|
191
|
+
// Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
|
|
192
|
+
// a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
|
|
193
|
+
retainTags: "HINDSIGHT_RETAIN_TAGS"
|
|
175
194
|
};
|
|
176
195
|
var ENV_BOOLEANS = /* @__PURE__ */ new Set([
|
|
177
196
|
"dynamicBankId",
|
|
@@ -182,6 +201,7 @@ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
|
|
|
182
201
|
"autoSeed",
|
|
183
202
|
"codebaseSurvey"
|
|
184
203
|
]);
|
|
204
|
+
var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
|
|
185
205
|
var ENV_NUMBERS = /* @__PURE__ */ new Set([
|
|
186
206
|
"apiPort",
|
|
187
207
|
"daemonIdleTimeout",
|
|
@@ -199,6 +219,9 @@ function readEnvConfig(env = process.env) {
|
|
|
199
219
|
if (value === void 0 || value.trim() === "") continue;
|
|
200
220
|
if (ENV_BOOLEANS.has(key)) {
|
|
201
221
|
out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
|
|
222
|
+
} else if (ENV_LISTS.has(key)) {
|
|
223
|
+
const items = value.split(",").map((v) => v.trim()).filter(Boolean);
|
|
224
|
+
if (items.length) out[key] = items;
|
|
202
225
|
} else if (ENV_NUMBERS.has(key)) {
|
|
203
226
|
const n = Number(value);
|
|
204
227
|
if (Number.isFinite(n)) out[key] = n;
|
|
@@ -413,6 +436,13 @@ var CODING_BANK_TEMPLATE = {
|
|
|
413
436
|
entities_allow_free_form: true
|
|
414
437
|
}
|
|
415
438
|
};
|
|
439
|
+
var CODING_BANK_STRUCTURE = {
|
|
440
|
+
version: "1",
|
|
441
|
+
bank: {
|
|
442
|
+
retain_strategies: RETAIN_STRATEGIES,
|
|
443
|
+
entity_labels: [KNOWLEDGE_LABELS]
|
|
444
|
+
}
|
|
445
|
+
};
|
|
416
446
|
|
|
417
447
|
// src/core/util.ts
|
|
418
448
|
var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
@@ -440,6 +470,7 @@ var KnowledgePagesUnavailableError = class extends Error {
|
|
|
440
470
|
}
|
|
441
471
|
};
|
|
442
472
|
var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
|
|
473
|
+
var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
|
|
443
474
|
var HindsightClient = class {
|
|
444
475
|
apiUrl;
|
|
445
476
|
apiToken;
|
|
@@ -556,12 +587,39 @@ var HindsightClient = class {
|
|
|
556
587
|
await this.req("DELETE", this.bankUrl());
|
|
557
588
|
this.log(`[bank] reset ${this.bank}`);
|
|
558
589
|
}
|
|
559
|
-
|
|
590
|
+
const seeded = opts.reset ? false : await this.hasBankMissions();
|
|
591
|
+
await this.req(
|
|
592
|
+
"POST",
|
|
593
|
+
this.bankUrl("/import"),
|
|
594
|
+
seeded ? CODING_BANK_STRUCTURE : CODING_BANK_TEMPLATE
|
|
595
|
+
);
|
|
560
596
|
this.log(
|
|
561
|
-
`[bank] template applied to ${this.bank}: missions, entity_labels {knowledge}, strategies {git, gitlog, conversation, document}`
|
|
597
|
+
seeded ? `[bank] structure applied to ${this.bank}: entity_labels {knowledge}, strategies {git, gitlog, conversation, document} \u2014 missions left as configured` : `[bank] template applied to ${this.bank}: missions, entity_labels {knowledge}, strategies {git, gitlog, conversation, document}`
|
|
562
598
|
);
|
|
563
599
|
await this.seedPages();
|
|
564
600
|
}
|
|
601
|
+
/**
|
|
602
|
+
* Whether this bank already carries bank-level mission overrides — ours from an earlier seed, or
|
|
603
|
+
* the user's own edit. Either way they are not ours to overwrite.
|
|
604
|
+
*
|
|
605
|
+
* Reads the bank-scoped OVERRIDES, not the resolved config, so inherited global defaults don't
|
|
606
|
+
* read as "already set". A missing bank, or a deployment with the bank-config API switched off,
|
|
607
|
+
* answers false: there is nothing to preserve, and without that API a user cannot set per-bank
|
|
608
|
+
* missions in the first place.
|
|
609
|
+
*/
|
|
610
|
+
async hasBankMissions() {
|
|
611
|
+
try {
|
|
612
|
+
const r = await this.req("GET", this.bankUrl("/config"));
|
|
613
|
+
if (!r.ok) return false;
|
|
614
|
+
const j = await r.json();
|
|
615
|
+
return MISSION_FIELDS.some((f) => {
|
|
616
|
+
const v = j.overrides?.[f];
|
|
617
|
+
return typeof v === "string" && v.trim() !== "";
|
|
618
|
+
});
|
|
619
|
+
} catch {
|
|
620
|
+
return false;
|
|
621
|
+
}
|
|
622
|
+
}
|
|
565
623
|
/** Delete one document (cascades its memory units/links). Used by deepen's self-cleanup. */
|
|
566
624
|
async deleteDocument(documentId) {
|
|
567
625
|
await this.req("DELETE", this.bankUrl(`/documents/${encodeURIComponent(documentId)}`));
|
|
@@ -931,14 +989,14 @@ function serialize(cursors, sessionId, write2) {
|
|
|
931
989
|
}
|
|
932
990
|
async function retainLiveSession(client, sessionId, turns, startTs, harness, opts = {}) {
|
|
933
991
|
const cursors = opts.cursors;
|
|
934
|
-
if (!cursors) return writeSession(client, sessionId, turns, startTs, harness);
|
|
992
|
+
if (!cursors) return writeSession(client, sessionId, turns, startTs, harness, opts.stamp);
|
|
935
993
|
return serialize(
|
|
936
994
|
cursors,
|
|
937
995
|
sessionId,
|
|
938
|
-
() => writeSession(client, sessionId, turns, startTs, harness, cursors)
|
|
996
|
+
() => writeSession(client, sessionId, turns, startTs, harness, opts.stamp, cursors)
|
|
939
997
|
);
|
|
940
998
|
}
|
|
941
|
-
async function writeSession(client, sessionId, turns, startTs, harness, cursors) {
|
|
999
|
+
async function writeSession(client, sessionId, turns, startTs, harness, stamp, cursors) {
|
|
942
1000
|
const refId = `conversation:${sessionId}`;
|
|
943
1001
|
const appendSupported = Boolean(cursors) && await supportsAppend(client);
|
|
944
1002
|
const plan = planRetain(turns, cursors?.read(sessionId), { appendSupported, bank: client.bank });
|
|
@@ -954,7 +1012,15 @@ async function writeSession(client, sessionId, turns, startTs, harness, cursors)
|
|
|
954
1012
|
content,
|
|
955
1013
|
"coding agent session",
|
|
956
1014
|
refId,
|
|
957
|
-
|
|
1015
|
+
// Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
|
|
1016
|
+
// the documents list filters and draws its agent logo from, so a template cannot displace them.
|
|
1017
|
+
[
|
|
1018
|
+
.../* @__PURE__ */ new Set([
|
|
1019
|
+
...stamp?.tags ?? [],
|
|
1020
|
+
"source:chat",
|
|
1021
|
+
...harness ? [`harness:${harness}`] : []
|
|
1022
|
+
])
|
|
1023
|
+
],
|
|
958
1024
|
"conversation",
|
|
959
1025
|
{
|
|
960
1026
|
timestamp: startTs,
|
|
@@ -966,6 +1032,8 @@ ${refId}
|
|
|
966
1032
|
${plan.mode}
|
|
967
1033
|
${content}`),
|
|
968
1034
|
metadata: {
|
|
1035
|
+
...stamp?.metadata,
|
|
1036
|
+
// configured first: the built-ins below win on any key collision
|
|
969
1037
|
source: "chat",
|
|
970
1038
|
session_id: sessionId,
|
|
971
1039
|
ref_id: refId,
|
|
@@ -1092,6 +1160,53 @@ function preflightDaemon(cfg, harness) {
|
|
|
1092
1160
|
return true;
|
|
1093
1161
|
}
|
|
1094
1162
|
|
|
1163
|
+
// src/core/retain-stamp.ts
|
|
1164
|
+
import { basename as basename2 } from "path";
|
|
1165
|
+
var RESERVED_TAG_PREFIX = /^(source|harness):/;
|
|
1166
|
+
function resolversFor(ctx) {
|
|
1167
|
+
return {
|
|
1168
|
+
// Worktree-aware like the bank id, so every linked worktree of a repo stamps the SAME name —
|
|
1169
|
+
// otherwise a shared bank ends up with `project:app` and `project:app-wt2` for one repository.
|
|
1170
|
+
gitProject: () => projectNameOf(ctx.directory),
|
|
1171
|
+
project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
|
|
1172
|
+
harness: () => ctx.harness,
|
|
1173
|
+
bankId: () => ctx.bankId,
|
|
1174
|
+
sessionId: () => ctx.sessionId,
|
|
1175
|
+
timestamp: () => (/* @__PURE__ */ new Date()).toISOString(),
|
|
1176
|
+
channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
|
|
1177
|
+
user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
|
|
1178
|
+
};
|
|
1179
|
+
}
|
|
1180
|
+
function buildRetainStamp(cfg, ctx) {
|
|
1181
|
+
const hasTags = Boolean(cfg.retainTags?.length);
|
|
1182
|
+
const hasMetadata = Boolean(cfg.retainMetadata && Object.keys(cfg.retainMetadata).length);
|
|
1183
|
+
if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
|
|
1184
|
+
const base = resolversFor(ctx);
|
|
1185
|
+
const cache = /* @__PURE__ */ new Map();
|
|
1186
|
+
const resolvers = Object.fromEntries(
|
|
1187
|
+
Object.entries(base).map(([name, resolve2]) => [
|
|
1188
|
+
name,
|
|
1189
|
+
() => {
|
|
1190
|
+
const hit = cache.get(name);
|
|
1191
|
+
if (hit !== void 0) return hit;
|
|
1192
|
+
const value = resolve2();
|
|
1193
|
+
cache.set(name, value);
|
|
1194
|
+
return value;
|
|
1195
|
+
}
|
|
1196
|
+
])
|
|
1197
|
+
);
|
|
1198
|
+
const tags = (cfg.retainTags ?? []).map((t) => applyTemplate(t, resolvers, "retainTags").trim()).filter(Boolean).filter((t) => {
|
|
1199
|
+
if (!RESERVED_TAG_PREFIX.test(t)) return true;
|
|
1200
|
+
log.warn("retain-stamp", "ignoring reserved retainTags entry", { tag: t });
|
|
1201
|
+
return false;
|
|
1202
|
+
});
|
|
1203
|
+
const metadata = {};
|
|
1204
|
+
for (const [key, value] of Object.entries(cfg.retainMetadata ?? {})) {
|
|
1205
|
+
metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
|
|
1206
|
+
}
|
|
1207
|
+
return { tags, metadata };
|
|
1208
|
+
}
|
|
1209
|
+
|
|
1095
1210
|
// src/core/jsonl.ts
|
|
1096
1211
|
import { closeSync, openSync, readSync, statSync } from "fs";
|
|
1097
1212
|
import { StringDecoder } from "string_decoder";
|
|
@@ -1154,7 +1269,7 @@ function* streamLines(path, start) {
|
|
|
1154
1269
|
}
|
|
1155
1270
|
|
|
1156
1271
|
// src/core/transcript-util.ts
|
|
1157
|
-
var MEMORY_TAG_RE = /<(hook_prompt|hindsight_memory|hindsight_memories|hindsight_bank|relevant_memories|user_feedback|hindsight_knowledge|hindsight_knowledge_refresh)\b[\s\S]*?<\/\1>/g;
|
|
1272
|
+
var MEMORY_TAG_RE = /<(hook_prompt|task-notification|system-reminder|hindsight_memory|hindsight_memories|hindsight_bank|relevant_memories|user_feedback|hindsight_knowledge|hindsight_knowledge_refresh)\b[\s\S]*?<\/\1>/g;
|
|
1158
1273
|
function stripInjectedMemory(s) {
|
|
1159
1274
|
return s.replace(MEMORY_TAG_RE, "");
|
|
1160
1275
|
}
|
|
@@ -1228,6 +1343,7 @@ function readClaudeTranscript(path) {
|
|
|
1228
1343
|
if (line.type !== "user" && line.type !== "assistant") continue;
|
|
1229
1344
|
if (line.isMeta === true) continue;
|
|
1230
1345
|
if (line.isSidechain === true) continue;
|
|
1346
|
+
if (line.isCompactSummary === true) continue;
|
|
1231
1347
|
if (typeof line.message !== "object" || line.message === null) continue;
|
|
1232
1348
|
for (const rendered of renderLine(line.message.content, line.type)) {
|
|
1233
1349
|
const turn = { role: rendered.role, content: rendered.content };
|
|
@@ -1248,7 +1364,8 @@ async function buildRetain(args) {
|
|
|
1248
1364
|
const t0 = Date.now();
|
|
1249
1365
|
try {
|
|
1250
1366
|
await retainLiveSession(client, sessionId, turns, startTs, harness, {
|
|
1251
|
-
cursors: args.cursors ?? fileCursorStore(harness)
|
|
1367
|
+
cursors: args.cursors ?? fileCursorStore(harness),
|
|
1368
|
+
stamp: args.stamp
|
|
1252
1369
|
});
|
|
1253
1370
|
diag(harness, "retain_ok", { ms: Date.now() - t0, turns: turns.length, session: sessionId });
|
|
1254
1371
|
} catch (e) {
|
|
@@ -1287,7 +1404,13 @@ async function runRetainHook(spec, makeClient = (o) => new HindsightClient(o)) {
|
|
|
1287
1404
|
sessionId: sessionId || "no-session",
|
|
1288
1405
|
transcriptPath,
|
|
1289
1406
|
client,
|
|
1290
|
-
readTranscript: spec.readTranscript
|
|
1407
|
+
readTranscript: spec.readTranscript,
|
|
1408
|
+
stamp: buildRetainStamp(cfg, {
|
|
1409
|
+
directory: cwd,
|
|
1410
|
+
harness: spec.harness,
|
|
1411
|
+
bankId,
|
|
1412
|
+
sessionId: sessionId || "no-session"
|
|
1413
|
+
})
|
|
1291
1414
|
});
|
|
1292
1415
|
}
|
|
1293
1416
|
|