@vectorize-io/hindsight-coding-agents 0.1.1 → 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.
@@ -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,20 +77,30 @@ 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
 
83
+ // src/core/retain-cursor.ts
84
+ import { createHash } from "crypto";
85
+
86
+ // src/core/uuid.ts
87
+ import { createHash as createHash2 } from "crypto";
88
+
76
89
  // src/core/util.ts
77
90
  var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
91
+ function semverGte(version, min) {
92
+ const parts = (v) => {
93
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
94
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
95
+ };
96
+ const a = version ? parts(version) : void 0;
97
+ const b = parts(min);
98
+ if (!a || !b) return false;
99
+ for (let i = 0; i < 3; i++) {
100
+ if (a[i] !== b[i]) return a[i] > b[i];
101
+ }
102
+ return true;
103
+ }
78
104
  async function pool(items, n, fn, onError, onProgress) {
79
105
  let i = 0, done = 0;
80
106
  async function worker() {
@@ -193,6 +219,12 @@ function resolveConfig(raw = {}) {
193
219
  surveyBudgetUsd: raw.surveyBudgetUsd || 2,
194
220
  surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
195
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
+ ) : {},
196
228
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
197
229
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
198
230
  };
@@ -246,7 +278,10 @@ var ENV_KEYS = {
246
278
  surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
247
279
  surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
248
280
  logLevel: "HINDSIGHT_LOG_LEVEL",
249
- 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"
250
285
  };
251
286
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
252
287
  "dynamicBankId",
@@ -257,6 +292,7 @@ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
257
292
  "autoSeed",
258
293
  "codebaseSurvey"
259
294
  ]);
295
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
260
296
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
261
297
  "apiPort",
262
298
  "daemonIdleTimeout",
@@ -274,6 +310,9 @@ function readEnvConfig(env = process.env) {
274
310
  if (value === void 0 || value.trim() === "") continue;
275
311
  if (ENV_BOOLEANS.has(key)) {
276
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;
277
316
  } else if (ENV_NUMBERS.has(key)) {
278
317
  const n = Number(value);
279
318
  if (Number.isFinite(n)) out[key] = n;
@@ -420,8 +459,7 @@ async function ingestGitLog(client, repo, opts = { limit: 300 }) {
420
459
  `git commit-message history (last ${n}) for ${repoName}`,
421
460
  `gitlog:${repoName}`,
422
461
  ["source:git", "source:git-log", ...head ? [`gitlog-head:${head}`] : []],
423
- "gitlog",
424
- { async: true }
462
+ "gitlog"
425
463
  );
426
464
  log3(`[gitlog] done: ${n} commit messages ingested as 1 document under strategy 'gitlog'`);
427
465
  return 0;
@@ -565,8 +603,16 @@ var CODING_BANK_TEMPLATE = {
565
603
  entities_allow_free_form: true
566
604
  }
567
605
  };
606
+ var CODING_BANK_STRUCTURE = {
607
+ version: "1",
608
+ bank: {
609
+ retain_strategies: RETAIN_STRATEGIES,
610
+ entity_labels: [KNOWLEDGE_LABELS]
611
+ }
612
+ };
568
613
 
569
614
  // src/core/hindsight.ts
615
+ var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
570
616
  var KnowledgePagesUnavailableError = class extends Error {
571
617
  code = "knowledge_pages_unavailable";
572
618
  constructor() {
@@ -575,6 +621,7 @@ var KnowledgePagesUnavailableError = class extends Error {
575
621
  }
576
622
  };
577
623
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
624
+ var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
578
625
  var HindsightClient = class {
579
626
  apiUrl;
580
627
  apiToken;
@@ -583,6 +630,8 @@ var HindsightClient = class {
583
630
  // async operation ids collected by retain(), for drain()
584
631
  /** Tri-state capability probe: unknown until the first page request, then cached. */
585
632
  knowledgePagesSupported;
633
+ /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
634
+ idempotentRetain;
586
635
  log;
587
636
  constructor(o) {
588
637
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
@@ -611,7 +660,8 @@ var HindsightClient = class {
611
660
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
612
661
  return r;
613
662
  }
614
- /** Retain one memory. Async by default: enqueue extraction server-side and collect its op-id for drain(). */
663
+ /** Retain one memory. ALWAYS async: enqueue extraction server-side and collect its op-id for
664
+ * drain(). Nothing in this plugin can afford to block a coding agent's hook on extraction. */
615
665
  async retain(content, context, documentId, tags, strategy, opts = {}) {
616
666
  const item = {
617
667
  content,
@@ -622,14 +672,36 @@ var HindsightClient = class {
622
672
  };
623
673
  if (opts.timestamp) item.timestamp = opts.timestamp;
624
674
  if (opts.metadata) item.metadata = opts.metadata;
625
- const isAsync = opts.async !== false;
626
- const r = await this.req("POST", this.bankUrl("/memories"), { items: [item], async: isAsync });
627
- if (isAsync) {
628
- try {
629
- const j = await r.json();
630
- if (j.operation_id) this.opIds.push(j.operation_id);
631
- } catch {
632
- }
675
+ if (opts.updateMode) item.update_mode = opts.updateMode;
676
+ const body = { items: [item], async: true };
677
+ if (opts.operationId) body.operation_id = opts.operationId;
678
+ const r = await this.req("POST", this.bankUrl("/memories"), body);
679
+ try {
680
+ const j = await r.json();
681
+ if (j.operation_id) this.opIds.push(j.operation_id);
682
+ } catch {
683
+ }
684
+ }
685
+ /**
686
+ * Whether this server honours `operation_id` on an async retain, and can therefore be appended to
687
+ * safely (see MIN_IDEMPOTENT_RETAIN_VERSION). Probed once per client via GET /version; anything
688
+ * unreachable, unparseable or older answers "no", which costs efficiency, never correctness.
689
+ */
690
+ async supportsIdempotentRetain() {
691
+ if (this.idempotentRetain === void 0) {
692
+ this.idempotentRetain = await this.probeIdempotentRetain();
693
+ this.log(`server retain idempotency: ${this.idempotentRetain ? "supported" : "unavailable"}`);
694
+ }
695
+ return this.idempotentRetain;
696
+ }
697
+ async probeIdempotentRetain() {
698
+ try {
699
+ const r = await this.req("GET", `${this.apiUrl}/version`);
700
+ if (!r.ok) return false;
701
+ const j = await r.json();
702
+ return semverGte(j.api_version, MIN_IDEMPOTENT_RETAIN_VERSION);
703
+ } catch {
704
+ return false;
633
705
  }
634
706
  }
635
707
  /**
@@ -666,12 +738,39 @@ var HindsightClient = class {
666
738
  await this.req("DELETE", this.bankUrl());
667
739
  this.log(`[bank] reset ${this.bank}`);
668
740
  }
669
- 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
+ );
670
747
  this.log(
671
- `[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}`
672
749
  );
673
750
  await this.seedPages();
674
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
+ }
675
774
  /** Delete one document (cascades its memory units/links). Used by deepen's self-cleanup. */
676
775
  async deleteDocument(documentId) {
677
776
  await this.req("DELETE", this.bankUrl(`/documents/${encodeURIComponent(documentId)}`));
@@ -917,8 +1016,7 @@ var HindsightClient = class {
917
1016
  "initiative marker",
918
1017
  markerId,
919
1018
  ["knowledge:feature-work", `relatedPageId:${pageId}`],
920
- "document",
921
- { async: true }
1019
+ "document"
922
1020
  );
923
1021
  return { page_id: pageId };
924
1022
  }
@@ -1211,8 +1309,7 @@ async function main() {
1211
1309
  "hindsight codebase-survey baseline",
1212
1310
  best.id,
1213
1311
  ["source:survey-baseline", "survey-state:done"],
1214
- "survey",
1215
- { async: true }
1312
+ "survey"
1216
1313
  );
1217
1314
  log2(`[survey] marker ${best.id} flipped to completed`);
1218
1315
  }