@vectorize-io/hindsight-coding-agents 0.1.2 → 0.2.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.
@@ -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).replace(PLACEHOLDER, (_, name) => {
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
- await this.req("POST", this.bankUrl("/import"), CODING_BANK_TEMPLATE);
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
- ["source:chat", ...harness ? [`harness:${harness}`] : []],
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
  }
@@ -1248,7 +1363,8 @@ async function buildRetain(args) {
1248
1363
  const t0 = Date.now();
1249
1364
  try {
1250
1365
  await retainLiveSession(client, sessionId, turns, startTs, harness, {
1251
- cursors: args.cursors ?? fileCursorStore(harness)
1366
+ cursors: args.cursors ?? fileCursorStore(harness),
1367
+ stamp: args.stamp
1252
1368
  });
1253
1369
  diag(harness, "retain_ok", { ms: Date.now() - t0, turns: turns.length, session: sessionId });
1254
1370
  } catch (e) {
@@ -1287,7 +1403,13 @@ async function runRetainHook(spec, makeClient = (o) => new HindsightClient(o)) {
1287
1403
  sessionId: sessionId || "no-session",
1288
1404
  transcriptPath,
1289
1405
  client,
1290
- readTranscript: spec.readTranscript
1406
+ readTranscript: spec.readTranscript,
1407
+ stamp: buildRetainStamp(cfg, {
1408
+ directory: cwd,
1409
+ harness: spec.harness,
1410
+ bankId,
1411
+ sessionId: sessionId || "no-session"
1412
+ })
1291
1413
  });
1292
1414
  }
1293
1415
 
@@ -345,6 +345,12 @@ function resolveConfig(raw = {}) {
345
345
  surveyBudgetUsd: raw.surveyBudgetUsd || 2,
346
346
  surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
347
347
  gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
348
+ // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
349
+ // nested object cannot reach the API as a tag and fail the whole retain.
350
+ retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
351
+ retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
352
+ Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
353
+ ) : {},
348
354
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
349
355
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
350
356
  };
@@ -398,7 +404,10 @@ var ENV_KEYS = {
398
404
  surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
399
405
  surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
400
406
  logLevel: "HINDSIGHT_LOG_LEVEL",
401
- gitIngest: "HINDSIGHT_GIT_INGEST"
407
+ gitIngest: "HINDSIGHT_GIT_INGEST",
408
+ // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
409
+ // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
410
+ retainTags: "HINDSIGHT_RETAIN_TAGS"
402
411
  };
403
412
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
404
413
  "dynamicBankId",
@@ -409,6 +418,7 @@ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
409
418
  "autoSeed",
410
419
  "codebaseSurvey"
411
420
  ]);
421
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
412
422
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
413
423
  "apiPort",
414
424
  "daemonIdleTimeout",
@@ -426,6 +436,9 @@ function readEnvConfig(env = process.env) {
426
436
  if (value === void 0 || value.trim() === "") continue;
427
437
  if (ENV_BOOLEANS.has(key)) {
428
438
  out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
439
+ } else if (ENV_LISTS.has(key)) {
440
+ const items = value.split(",").map((v) => v.trim()).filter(Boolean);
441
+ if (items.length) out[key] = items;
429
442
  } else if (ENV_NUMBERS.has(key)) {
430
443
  const n = Number(value);
431
444
  if (Number.isFinite(n)) out[key] = n;
package/dist/deepen.js CHANGED
@@ -10,9 +10,25 @@ import { join as join6 } from "path";
10
10
  import { execFileSync } from "child_process";
11
11
  import { homedir } from "os";
12
12
  import { basename, dirname, join, normalize, sep } from "path";
13
+
14
+ // src/core/template.ts
15
+ var PLACEHOLDER = /\{([a-zA-Z_]+)\}/g;
16
+ function applyTemplate(template, resolvers, what) {
17
+ return template.replace(PLACEHOLDER, (_, name) => {
18
+ const resolve2 = resolvers[name];
19
+ if (!resolve2) {
20
+ console.error(
21
+ `hindsight: unknown ${what} placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
22
+ );
23
+ return "unknown";
24
+ }
25
+ return resolve2();
26
+ });
27
+ }
28
+
29
+ // src/core/bank.ts
13
30
  var DEFAULT_BANK_NAME = "coding";
14
31
  var DEFAULT_TEMPLATE = "coding-agent::{gitProject}";
15
- var PLACEHOLDER = /\{([a-zA-Z]+)\}/g;
16
32
  function getProjectRootFromGit(directory) {
17
33
  if (!directory) return null;
18
34
  try {
@@ -61,16 +77,7 @@ function deriveBankId(config, directory, harness = "coding") {
61
77
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
62
78
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
63
79
  };
64
- return (config.bankIdTemplate || DEFAULT_TEMPLATE).replace(PLACEHOLDER, (_, name) => {
65
- const r = resolvers[name];
66
- if (!r) {
67
- console.error(
68
- `hindsight: unknown bankIdTemplate placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
69
- );
70
- return "unknown";
71
- }
72
- return r();
73
- });
80
+ return applyTemplate(config.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
74
81
  }
75
82
 
76
83
  // src/core/retain-cursor.ts
@@ -212,6 +219,12 @@ function resolveConfig(raw = {}) {
212
219
  surveyBudgetUsd: raw.surveyBudgetUsd || 2,
213
220
  surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
214
221
  gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
222
+ // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
223
+ // nested object cannot reach the API as a tag and fail the whole retain.
224
+ retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
225
+ retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
226
+ Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
227
+ ) : {},
215
228
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
216
229
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
217
230
  };
@@ -265,7 +278,10 @@ var ENV_KEYS = {
265
278
  surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
266
279
  surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
267
280
  logLevel: "HINDSIGHT_LOG_LEVEL",
268
- gitIngest: "HINDSIGHT_GIT_INGEST"
281
+ gitIngest: "HINDSIGHT_GIT_INGEST",
282
+ // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
283
+ // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
284
+ retainTags: "HINDSIGHT_RETAIN_TAGS"
269
285
  };
270
286
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
271
287
  "dynamicBankId",
@@ -276,6 +292,7 @@ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
276
292
  "autoSeed",
277
293
  "codebaseSurvey"
278
294
  ]);
295
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
279
296
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
280
297
  "apiPort",
281
298
  "daemonIdleTimeout",
@@ -293,6 +310,9 @@ function readEnvConfig(env = process.env) {
293
310
  if (value === void 0 || value.trim() === "") continue;
294
311
  if (ENV_BOOLEANS.has(key)) {
295
312
  out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
313
+ } else if (ENV_LISTS.has(key)) {
314
+ const items = value.split(",").map((v) => v.trim()).filter(Boolean);
315
+ if (items.length) out[key] = items;
296
316
  } else if (ENV_NUMBERS.has(key)) {
297
317
  const n = Number(value);
298
318
  if (Number.isFinite(n)) out[key] = n;
@@ -583,6 +603,13 @@ var CODING_BANK_TEMPLATE = {
583
603
  entities_allow_free_form: true
584
604
  }
585
605
  };
606
+ var CODING_BANK_STRUCTURE = {
607
+ version: "1",
608
+ bank: {
609
+ retain_strategies: RETAIN_STRATEGIES,
610
+ entity_labels: [KNOWLEDGE_LABELS]
611
+ }
612
+ };
586
613
 
587
614
  // src/core/hindsight.ts
588
615
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
@@ -594,6 +621,7 @@ var KnowledgePagesUnavailableError = class extends Error {
594
621
  }
595
622
  };
596
623
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
624
+ var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
597
625
  var HindsightClient = class {
598
626
  apiUrl;
599
627
  apiToken;
@@ -710,12 +738,39 @@ var HindsightClient = class {
710
738
  await this.req("DELETE", this.bankUrl());
711
739
  this.log(`[bank] reset ${this.bank}`);
712
740
  }
713
- await this.req("POST", this.bankUrl("/import"), CODING_BANK_TEMPLATE);
741
+ const seeded = opts.reset ? false : await this.hasBankMissions();
742
+ await this.req(
743
+ "POST",
744
+ this.bankUrl("/import"),
745
+ seeded ? CODING_BANK_STRUCTURE : CODING_BANK_TEMPLATE
746
+ );
714
747
  this.log(
715
- `[bank] template applied to ${this.bank}: missions, entity_labels {knowledge}, strategies {git, gitlog, conversation, document}`
748
+ 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}`
716
749
  );
717
750
  await this.seedPages();
718
751
  }
752
+ /**
753
+ * Whether this bank already carries bank-level mission overrides — ours from an earlier seed, or
754
+ * the user's own edit. Either way they are not ours to overwrite.
755
+ *
756
+ * Reads the bank-scoped OVERRIDES, not the resolved config, so inherited global defaults don't
757
+ * read as "already set". A missing bank, or a deployment with the bank-config API switched off,
758
+ * answers false: there is nothing to preserve, and without that API a user cannot set per-bank
759
+ * missions in the first place.
760
+ */
761
+ async hasBankMissions() {
762
+ try {
763
+ const r = await this.req("GET", this.bankUrl("/config"));
764
+ if (!r.ok) return false;
765
+ const j = await r.json();
766
+ return MISSION_FIELDS.some((f) => {
767
+ const v = j.overrides?.[f];
768
+ return typeof v === "string" && v.trim() !== "";
769
+ });
770
+ } catch {
771
+ return false;
772
+ }
773
+ }
719
774
  /** Delete one document (cascades its memory units/links). Used by deepen's self-cleanup. */
720
775
  async deleteDocument(documentId) {
721
776
  await this.req("DELETE", this.bankUrl(`/documents/${encodeURIComponent(documentId)}`));
@@ -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).replace(PLACEHOLDER, (_, name) => {
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
- await this.req("POST", this.bankUrl("/import"), CODING_BANK_TEMPLATE);
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
  }