@vectorize-io/hindsight-coding-agents 0.2.1 → 0.3.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.
@@ -1,10 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  // src/core/hook.ts
4
- import { existsSync, readFileSync as readFileSync3 } from "fs";
4
+ import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
5
5
 
6
6
  // src/core/bank.ts
7
7
  import { execFileSync } from "child_process";
8
+ import { existsSync } from "fs";
8
9
  import { homedir } from "os";
9
10
  import { basename, dirname, join, normalize, sep } from "path";
10
11
 
@@ -40,25 +41,59 @@ function getProjectRootFromGit(directory) {
40
41
  return null;
41
42
  }
42
43
  }
44
+ var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
45
+ function nearestExistingDir(directory) {
46
+ let current2 = directory;
47
+ while (current2) {
48
+ if (existsSync(current2)) return current2;
49
+ const parent = dirname(current2);
50
+ if (parent === current2) return "";
51
+ current2 = parent;
52
+ }
53
+ return "";
54
+ }
55
+ function dirName(directory) {
56
+ return directory && basename(directory) || "unknown";
57
+ }
43
58
  function gitProjectName(directory, resolveWorktrees) {
44
59
  if (resolveWorktrees) {
45
- const root = getProjectRootFromGit(directory);
46
- if (root) return basename(root);
60
+ const candidates = [
61
+ nearestExistingDir(directory),
62
+ ...PROJECT_ROOT_ENV.map((v) => process.env[v] || "")
63
+ ];
64
+ for (const candidate of candidates) {
65
+ const root = candidate ? getProjectRootFromGit(candidate) : null;
66
+ if (root) return basename(root);
67
+ }
47
68
  }
48
- return directory ? basename(directory) : "unknown";
69
+ return dirName(directory);
70
+ }
71
+ function configuredDir(dir) {
72
+ const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
73
+ return normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
74
+ }
75
+ function isWithin(directory, configured) {
76
+ return directory === configured || directory.startsWith(configured + sep);
49
77
  }
50
78
  function mapLookup(map, directory) {
51
79
  const cwd = normalize(directory);
52
80
  let best;
53
81
  for (const [dir, bank] of Object.entries(map)) {
54
- const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
55
- const p = normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
56
- if (cwd === p || cwd.startsWith(p + sep)) {
82
+ const p = configuredDir(dir);
83
+ if (isWithin(cwd, p)) {
57
84
  if (!best || p.length > best.len) best = { len: p.length, bank };
58
85
  }
59
86
  }
60
87
  return best?.bank;
61
88
  }
89
+ function isOptedIn(config, directory) {
90
+ if (!config.optInOnly) return true;
91
+ if (!directory) return false;
92
+ const cwd = normalize(directory);
93
+ if ((config.optInPaths ?? []).some((dir) => dir && isWithin(cwd, configuredDir(dir))))
94
+ return true;
95
+ return Boolean(config.mapPathToBank && mapLookup(config.mapPathToBank, directory));
96
+ }
62
97
  function deriveBankId(config, directory, harness = "coding") {
63
98
  const mapped = directory && config.mapPathToBank ? mapLookup(config.mapPathToBank, directory) : void 0;
64
99
  if (mapped) return mapped;
@@ -66,7 +101,7 @@ function deriveBankId(config, directory, harness = "coding") {
66
101
  if (!dynamic) return config.bankId || DEFAULT_BANK_NAME;
67
102
  const resolvers = {
68
103
  harness: () => harness,
69
- project: () => directory ? basename(directory) : "unknown",
104
+ project: () => dirName(directory),
70
105
  gitProject: () => gitProjectName(directory, config.resolveWorktrees ?? true),
71
106
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
72
107
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -136,11 +171,14 @@ function resolveConfig(raw = {}) {
136
171
  bankIdTemplate: raw.bankIdTemplate,
137
172
  mapPathToBank: raw.mapPathToBank,
138
173
  resolveWorktrees: raw.resolveWorktrees,
174
+ optInOnly: raw.optInOnly ?? false,
175
+ // Same shape as retainTags: a config typo must not become a path that silently approves nothing.
176
+ optInPaths: Array.isArray(raw.optInPaths) ? raw.optInPaths.filter((p) => typeof p === "string" && p.trim() !== "") : [],
139
177
  harness: raw.harness ?? "opencode",
140
178
  disabled: raw.disabled ?? false,
141
179
  retainSessions: raw.retainSessions ?? true,
142
180
  // opencode: write back by default (parity with hook-harness Stop)
143
- retainEveryTurns: raw.retainEveryTurns || 1,
181
+ maxParallelRetains: raw.maxParallelRetains || 10,
144
182
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
145
183
  autoReflect: raw.autoReflect ?? true,
146
184
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
@@ -196,10 +234,12 @@ var ENV_KEYS = {
196
234
  dynamicBankId: "HINDSIGHT_DYNAMIC_BANK_ID",
197
235
  bankIdTemplate: "HINDSIGHT_BANK_ID_TEMPLATE",
198
236
  resolveWorktrees: "HINDSIGHT_RESOLVE_WORKTREES",
237
+ optInOnly: "HINDSIGHT_OPT_IN_ONLY",
238
+ optInPaths: "HINDSIGHT_OPT_IN_PATHS",
199
239
  harness: "HINDSIGHT_HARNESS",
200
240
  disabled: "HINDSIGHT_DISABLED",
201
241
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
202
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
242
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
203
243
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
204
244
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
205
245
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
@@ -218,17 +258,18 @@ var ENV_KEYS = {
218
258
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
219
259
  "dynamicBankId",
220
260
  "resolveWorktrees",
261
+ "optInOnly",
221
262
  "disabled",
222
263
  "retainSessions",
223
264
  "autoReflect",
224
265
  "autoSeed",
225
266
  "codebaseSurvey"
226
267
  ]);
227
- var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
268
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags", "optInPaths"]);
228
269
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
229
270
  "apiPort",
230
271
  "daemonIdleTimeout",
231
- "retainEveryTurns",
272
+ "maxParallelRetains",
232
273
  "reflectTimeoutMs",
233
274
  "pageRefreshEveryTurns",
234
275
  "seedLimit",
@@ -268,9 +309,15 @@ var BANK_OVERRIDE_EXCLUDED = [
268
309
  "mapPathToBank",
269
310
  "dynamicBankId",
270
311
  "resolveWorktrees",
312
+ // Approval is decided BEFORE the bank is resolved, so a `banks.<id>` section naming these could
313
+ // only ever arrive too late to matter — strip them rather than let them read as effective.
314
+ "optInOnly",
315
+ "optInPaths",
271
316
  "harness"
272
317
  ];
273
- function applyBankConfig(cfg, resolvedId) {
318
+ function applyBankConfig(cfg, resolvedId, directory) {
319
+ if (directory !== void 0 && !isOptedIn(cfg, directory))
320
+ return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
274
321
  const section = cfg.banks[resolvedId];
275
322
  if (!section) return { cfg, bankId: resolvedId };
276
323
  const safe = { ...section };
@@ -482,9 +529,40 @@ function semverGte(version, min) {
482
529
  }
483
530
  return true;
484
531
  }
532
+ async function pool(items, n, fn, onError, onProgress) {
533
+ let i = 0, done = 0;
534
+ async function worker() {
535
+ while (i < items.length) {
536
+ const idx = i++;
537
+ try {
538
+ await fn(items[idx], idx);
539
+ } catch (e) {
540
+ onError?.(idx, e);
541
+ }
542
+ onProgress?.(++done, items.length);
543
+ }
544
+ }
545
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
546
+ }
485
547
 
486
548
  // src/core/hindsight.ts
487
549
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
550
+ var RateLimitedError = class extends Error {
551
+ constructor(retryAfterMs2) {
552
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
553
+ this.retryAfterMs = retryAfterMs2;
554
+ this.name = "RateLimitedError";
555
+ }
556
+ retryAfterMs;
557
+ code = "rate_limited";
558
+ };
559
+ function retryAfterMs(header) {
560
+ if (!header) return 0;
561
+ const secs = Number(header.trim());
562
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
563
+ const at = Date.parse(header);
564
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
565
+ }
488
566
  var KnowledgePagesUnavailableError = class extends Error {
489
567
  code = "knowledge_pages_unavailable";
490
568
  constructor() {
@@ -493,6 +571,10 @@ var KnowledgePagesUnavailableError = class extends Error {
493
571
  }
494
572
  };
495
573
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
574
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
575
+ var POLL_CYCLE_MS = 5e3;
576
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
577
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
496
578
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
497
579
  var HindsightClient = class {
498
580
  apiUrl;
@@ -505,12 +587,14 @@ var HindsightClient = class {
505
587
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
506
588
  idempotentRetain;
507
589
  log;
590
+ maxParallelRetains;
508
591
  constructor(o) {
509
592
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
510
593
  this.apiToken = o.apiToken;
511
594
  this.bank = o.bank;
512
595
  this.log = o.log ?? (() => {
513
596
  });
597
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
514
598
  }
515
599
  headers() {
516
600
  const h = { "Content-Type": "application/json" };
@@ -528,6 +612,8 @@ var HindsightClient = class {
528
612
  body: body ? JSON.stringify(body) : void 0,
529
613
  signal: AbortSignal.timeout(15e3)
530
614
  });
615
+ if (r.status === 429 && !tolerate.includes(429))
616
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
531
617
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
532
618
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
533
619
  return r;
@@ -659,7 +745,14 @@ var HindsightClient = class {
659
745
  return 0;
660
746
  }
661
747
  }
662
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
748
+ /**
749
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
750
+ *
751
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
752
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
753
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
754
+ * of hammering the next cycle 5s later.
755
+ */
663
756
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
664
757
  if (!ids.length) return;
665
758
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -667,23 +760,29 @@ var HindsightClient = class {
667
760
  const pending = new Set(ids);
668
761
  let failed = 0;
669
762
  while (pending.size && Date.now() - start < maxMs) {
670
- await Promise.all(
671
- [...pending].map(async (id) => {
672
- try {
673
- const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
674
- if (!r.ok) return;
675
- const st = ((await r.json()).status || "").toLowerCase();
676
- if (TERMINAL.has(st)) {
677
- pending.delete(id);
678
- if (st !== "completed") failed++;
679
- }
680
- } catch {
763
+ let backoffMs = POLL_CYCLE_MS;
764
+ await pool([...pending], this.maxParallelRetains, async (id) => {
765
+ try {
766
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
767
+ if (r.status === 429) {
768
+ backoffMs = Math.min(
769
+ RETRY_AFTER_CEILING_MS,
770
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
771
+ );
772
+ return;
681
773
  }
682
- })
683
- );
774
+ if (!r.ok) return;
775
+ const st = ((await r.json()).status || "").toLowerCase();
776
+ if (TERMINAL.has(st)) {
777
+ pending.delete(id);
778
+ if (st !== "completed") failed++;
779
+ }
780
+ } catch {
781
+ }
782
+ });
684
783
  if (pending.size) {
685
784
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
686
- await sleep(5e3);
785
+ await sleep(backoffMs);
687
786
  }
688
787
  }
689
788
  this.log(
@@ -883,13 +982,20 @@ var HindsightClient = class {
883
982
  const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
884
983
  const content = `${verb}: ${args.title}. ${args.summary}`;
885
984
  const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
886
- await this.retain(
887
- content,
888
- "initiative marker",
889
- markerId,
890
- ["knowledge:feature-work", `relatedPageId:${pageId}`],
891
- "document"
892
- );
985
+ const tags = [
986
+ .../* @__PURE__ */ new Set([
987
+ ...args.stamp?.tags ?? [],
988
+ "knowledge:feature-work",
989
+ `relatedPageId:${pageId}`
990
+ ])
991
+ ];
992
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
993
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
994
+ metadata: args.stamp?.metadata
995
+ });
996
+ } else {
997
+ await this.retain(content, "initiative marker", markerId, tags, "document");
998
+ }
893
999
  return { page_id: pageId };
894
1000
  }
895
1001
  /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
@@ -988,7 +1094,7 @@ ${toolGuide(opts)}
988
1094
  }
989
1095
 
990
1096
  // src/core/session-cache.ts
991
- import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
1097
+ import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync } from "fs";
992
1098
  import { tmpdir as tmpdir2 } from "os";
993
1099
  import { dirname as dirname4, join as join5 } from "path";
994
1100
  function sessionCacheFile(harness, sessionId) {
@@ -1001,10 +1107,23 @@ function readSessionCache(cacheFile) {
1001
1107
  return {};
1002
1108
  }
1003
1109
  }
1110
+ function writeFileAtomic(path, body) {
1111
+ mkdirSync2(dirname4(path), { recursive: true });
1112
+ const tmp = `${path}.${process.pid}.tmp`;
1113
+ try {
1114
+ writeFileSync(tmp, body);
1115
+ renameSync(tmp, path);
1116
+ } catch (e) {
1117
+ try {
1118
+ rmSync(tmp, { force: true });
1119
+ } catch {
1120
+ }
1121
+ throw e;
1122
+ }
1123
+ }
1004
1124
  function writeSessionCache(cacheFile, cache) {
1005
1125
  try {
1006
- mkdirSync2(dirname4(cacheFile), { recursive: true });
1007
- writeFileSync(cacheFile, JSON.stringify(cache));
1126
+ writeFileAtomic(cacheFile, JSON.stringify(cache));
1008
1127
  } catch {
1009
1128
  }
1010
1129
  }
@@ -1025,7 +1144,10 @@ async function buildHookOutput(args) {
1025
1144
  const t0 = Date.now();
1026
1145
  try {
1027
1146
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
1028
- budget: "high",
1147
+ // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
1148
+ // supported default for bounded reflect calls; callers that explicitly invoke the MCP
1149
+ // tool still get the deeper high-budget path.
1150
+ budget: "low",
1029
1151
  timeoutMs: Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS)
1030
1152
  });
1031
1153
  diag(harness, reflectAnswer ? "reflect_ok" : "reflect_empty", {
@@ -1108,16 +1230,21 @@ async function runHook(spec, makeClient = (o) => new HindsightClient(o)) {
1108
1230
  return;
1109
1231
  }
1110
1232
  const out = (context, notice) => process.stdout.write(JSON.stringify(spec.emit(context ?? "", notice, ev)));
1111
- const resolved = applyBankConfig(cfg, deriveBankId(cfg, cwd, spec.harness));
1233
+ const resolved = applyBankConfig(cfg, deriveBankId(cfg, cwd, spec.harness), cwd);
1112
1234
  cfg = resolved.cfg;
1113
1235
  const bankId = resolved.bankId;
1114
1236
  if (cfg.disabled) {
1115
1237
  log.debug(spec.harness, "hook skipped: bank disabled via banks override", { bank: bankId });
1116
1238
  return;
1117
1239
  }
1118
- const client = makeClient({ apiUrl: cfg.apiUrl, apiToken: cfg.apiToken, bank: bankId });
1240
+ const client = makeClient({
1241
+ apiUrl: cfg.apiUrl,
1242
+ apiToken: cfg.apiToken,
1243
+ bank: bankId,
1244
+ maxParallelRetains: cfg.maxParallelRetains
1245
+ });
1119
1246
  const cacheFile = sessionCacheFile(spec.harness, sessionId || "no-session");
1120
- if (cfg.autoSeed !== false && !existsSync(cacheFile)) {
1247
+ if (cfg.autoSeed !== false && !existsSync2(cacheFile)) {
1121
1248
  startBackgroundSeed(cwd, { limit: cfg.seedLimit, harness: spec.harness });
1122
1249
  }
1123
1250
  const output = await buildHookOutput({ harness: spec.harness, prompt, cfg, client, cacheFile });
@@ -1252,13 +1379,13 @@ import { execFileSync as execFileSync4 } from "child_process";
1252
1379
 
1253
1380
  // src/core/survey.ts
1254
1381
  import { spawn as realSpawn3 } from "child_process";
1255
- import { accessSync, constants, existsSync as existsSync2 } from "fs";
1382
+ import { accessSync, constants, existsSync as existsSync3 } from "fs";
1256
1383
  import { homedir as homedir3 } from "os";
1257
1384
  import { delimiter, dirname as dirname6, join as join7 } from "path";
1258
1385
  import { fileURLToPath as fileURLToPath3 } from "url";
1259
1386
 
1260
1387
  // src/core/skill-sync.ts
1261
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
1388
+ import { cpSync, existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
1262
1389
  import { homedir as homedir4 } from "os";
1263
1390
  import { dirname as dirname7, join as join8 } from "path";
1264
1391
  import { fileURLToPath as fileURLToPath4 } from "url";
@@ -1393,14 +1520,14 @@ function readCopilotTranscript(path) {
1393
1520
  }
1394
1521
 
1395
1522
  // src/core/transcript-grok.ts
1396
- import { existsSync as existsSync4, readFileSync as readFileSync7, readdirSync } from "fs";
1523
+ import { existsSync as existsSync5, readFileSync as readFileSync7, readdirSync } from "fs";
1397
1524
  import { homedir as homedir5 } from "os";
1398
1525
  import { join as join9 } from "path";
1399
1526
  var CHAT_HISTORY = "chat_history.jsonl";
1400
1527
  function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME || join9(homedir5(), ".grok")) {
1401
1528
  const sessionsDir = join9(grokHome, "sessions");
1402
1529
  const direct = join9(sessionsDir, encodeURIComponent(cwd), sessionId, CHAT_HISTORY);
1403
- if (existsSync4(direct)) return direct;
1530
+ if (existsSync5(direct)) return direct;
1404
1531
  try {
1405
1532
  for (const candidate of readdirSync(sessionsDir)) {
1406
1533
  const directory = join9(sessionsDir, candidate);
@@ -1440,7 +1567,7 @@ function readGrokTranscript(path) {
1440
1567
  }
1441
1568
 
1442
1569
  // src/core/transcript-devin.ts
1443
- import { existsSync as existsSync5 } from "fs";
1570
+ import { existsSync as existsSync6 } from "fs";
1444
1571
  import { createRequire } from "module";
1445
1572
  import { homedir as homedir6 } from "os";
1446
1573
  import { join as join10 } from "path";
@@ -1482,7 +1609,7 @@ function readDevinTranscript(sessionId, dbPath = devinSessionDb()) {
1482
1609
  diag("devin-cli", "sqlite_unavailable", { node: process.version, dbPath });
1483
1610
  return [];
1484
1611
  }
1485
- if (!existsSync5(dbPath)) {
1612
+ if (!existsSync6(dbPath)) {
1486
1613
  diag("devin-cli", "session_db_missing", { dbPath });
1487
1614
  return [];
1488
1615
  }