@vectorize-io/hindsight-coding-agents 0.2.1 → 0.3.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.
@@ -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,12 +41,32 @@ 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);
49
70
  }
50
71
  function mapLookup(map, directory) {
51
72
  const cwd = normalize(directory);
@@ -66,7 +87,7 @@ function deriveBankId(config, directory, harness = "coding") {
66
87
  if (!dynamic) return config.bankId || DEFAULT_BANK_NAME;
67
88
  const resolvers = {
68
89
  harness: () => harness,
69
- project: () => directory ? basename(directory) : "unknown",
90
+ project: () => dirName(directory),
70
91
  gitProject: () => gitProjectName(directory, config.resolveWorktrees ?? true),
71
92
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
72
93
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -140,7 +161,7 @@ function resolveConfig(raw = {}) {
140
161
  disabled: raw.disabled ?? false,
141
162
  retainSessions: raw.retainSessions ?? true,
142
163
  // opencode: write back by default (parity with hook-harness Stop)
143
- retainEveryTurns: raw.retainEveryTurns || 1,
164
+ maxParallelRetains: raw.maxParallelRetains || 10,
144
165
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
145
166
  autoReflect: raw.autoReflect ?? true,
146
167
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
@@ -199,7 +220,7 @@ var ENV_KEYS = {
199
220
  harness: "HINDSIGHT_HARNESS",
200
221
  disabled: "HINDSIGHT_DISABLED",
201
222
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
202
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
223
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
203
224
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
204
225
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
205
226
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
@@ -228,7 +249,7 @@ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
228
249
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
229
250
  "apiPort",
230
251
  "daemonIdleTimeout",
231
- "retainEveryTurns",
252
+ "maxParallelRetains",
232
253
  "reflectTimeoutMs",
233
254
  "pageRefreshEveryTurns",
234
255
  "seedLimit",
@@ -482,9 +503,40 @@ function semverGte(version, min) {
482
503
  }
483
504
  return true;
484
505
  }
506
+ async function pool(items, n, fn, onError, onProgress) {
507
+ let i = 0, done = 0;
508
+ async function worker() {
509
+ while (i < items.length) {
510
+ const idx = i++;
511
+ try {
512
+ await fn(items[idx], idx);
513
+ } catch (e) {
514
+ onError?.(idx, e);
515
+ }
516
+ onProgress?.(++done, items.length);
517
+ }
518
+ }
519
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
520
+ }
485
521
 
486
522
  // src/core/hindsight.ts
487
523
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
524
+ var RateLimitedError = class extends Error {
525
+ constructor(retryAfterMs2) {
526
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
527
+ this.retryAfterMs = retryAfterMs2;
528
+ this.name = "RateLimitedError";
529
+ }
530
+ retryAfterMs;
531
+ code = "rate_limited";
532
+ };
533
+ function retryAfterMs(header) {
534
+ if (!header) return 0;
535
+ const secs = Number(header.trim());
536
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
537
+ const at = Date.parse(header);
538
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
539
+ }
488
540
  var KnowledgePagesUnavailableError = class extends Error {
489
541
  code = "knowledge_pages_unavailable";
490
542
  constructor() {
@@ -493,6 +545,10 @@ var KnowledgePagesUnavailableError = class extends Error {
493
545
  }
494
546
  };
495
547
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
548
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
549
+ var POLL_CYCLE_MS = 5e3;
550
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
551
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
496
552
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
497
553
  var HindsightClient = class {
498
554
  apiUrl;
@@ -505,12 +561,14 @@ var HindsightClient = class {
505
561
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
506
562
  idempotentRetain;
507
563
  log;
564
+ maxParallelRetains;
508
565
  constructor(o) {
509
566
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
510
567
  this.apiToken = o.apiToken;
511
568
  this.bank = o.bank;
512
569
  this.log = o.log ?? (() => {
513
570
  });
571
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
514
572
  }
515
573
  headers() {
516
574
  const h = { "Content-Type": "application/json" };
@@ -528,6 +586,8 @@ var HindsightClient = class {
528
586
  body: body ? JSON.stringify(body) : void 0,
529
587
  signal: AbortSignal.timeout(15e3)
530
588
  });
589
+ if (r.status === 429 && !tolerate.includes(429))
590
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
531
591
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
532
592
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
533
593
  return r;
@@ -659,7 +719,14 @@ var HindsightClient = class {
659
719
  return 0;
660
720
  }
661
721
  }
662
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
722
+ /**
723
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
724
+ *
725
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
726
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
727
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
728
+ * of hammering the next cycle 5s later.
729
+ */
663
730
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
664
731
  if (!ids.length) return;
665
732
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -667,23 +734,29 @@ var HindsightClient = class {
667
734
  const pending = new Set(ids);
668
735
  let failed = 0;
669
736
  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 {
737
+ let backoffMs = POLL_CYCLE_MS;
738
+ await pool([...pending], this.maxParallelRetains, async (id) => {
739
+ try {
740
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
741
+ if (r.status === 429) {
742
+ backoffMs = Math.min(
743
+ RETRY_AFTER_CEILING_MS,
744
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
745
+ );
746
+ return;
681
747
  }
682
- })
683
- );
748
+ if (!r.ok) return;
749
+ const st = ((await r.json()).status || "").toLowerCase();
750
+ if (TERMINAL.has(st)) {
751
+ pending.delete(id);
752
+ if (st !== "completed") failed++;
753
+ }
754
+ } catch {
755
+ }
756
+ });
684
757
  if (pending.size) {
685
758
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
686
- await sleep(5e3);
759
+ await sleep(backoffMs);
687
760
  }
688
761
  }
689
762
  this.log(
@@ -883,13 +956,20 @@ var HindsightClient = class {
883
956
  const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
884
957
  const content = `${verb}: ${args.title}. ${args.summary}`;
885
958
  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
- );
959
+ const tags = [
960
+ .../* @__PURE__ */ new Set([
961
+ ...args.stamp?.tags ?? [],
962
+ "knowledge:feature-work",
963
+ `relatedPageId:${pageId}`
964
+ ])
965
+ ];
966
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
967
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
968
+ metadata: args.stamp?.metadata
969
+ });
970
+ } else {
971
+ await this.retain(content, "initiative marker", markerId, tags, "document");
972
+ }
893
973
  return { page_id: pageId };
894
974
  }
895
975
  /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
@@ -988,7 +1068,7 @@ ${toolGuide(opts)}
988
1068
  }
989
1069
 
990
1070
  // src/core/session-cache.ts
991
- import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
1071
+ import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync } from "fs";
992
1072
  import { tmpdir as tmpdir2 } from "os";
993
1073
  import { dirname as dirname4, join as join5 } from "path";
994
1074
  function sessionCacheFile(harness, sessionId) {
@@ -1001,10 +1081,23 @@ function readSessionCache(cacheFile) {
1001
1081
  return {};
1002
1082
  }
1003
1083
  }
1084
+ function writeFileAtomic(path, body) {
1085
+ mkdirSync2(dirname4(path), { recursive: true });
1086
+ const tmp = `${path}.${process.pid}.tmp`;
1087
+ try {
1088
+ writeFileSync(tmp, body);
1089
+ renameSync(tmp, path);
1090
+ } catch (e) {
1091
+ try {
1092
+ rmSync(tmp, { force: true });
1093
+ } catch {
1094
+ }
1095
+ throw e;
1096
+ }
1097
+ }
1004
1098
  function writeSessionCache(cacheFile, cache) {
1005
1099
  try {
1006
- mkdirSync2(dirname4(cacheFile), { recursive: true });
1007
- writeFileSync(cacheFile, JSON.stringify(cache));
1100
+ writeFileAtomic(cacheFile, JSON.stringify(cache));
1008
1101
  } catch {
1009
1102
  }
1010
1103
  }
@@ -1025,7 +1118,10 @@ async function buildHookOutput(args) {
1025
1118
  const t0 = Date.now();
1026
1119
  try {
1027
1120
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
1028
- budget: "high",
1121
+ // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
1122
+ // supported default for bounded reflect calls; callers that explicitly invoke the MCP
1123
+ // tool still get the deeper high-budget path.
1124
+ budget: "low",
1029
1125
  timeoutMs: Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS)
1030
1126
  });
1031
1127
  diag(harness, reflectAnswer ? "reflect_ok" : "reflect_empty", {
@@ -1115,9 +1211,14 @@ async function runHook(spec, makeClient = (o) => new HindsightClient(o)) {
1115
1211
  log.debug(spec.harness, "hook skipped: bank disabled via banks override", { bank: bankId });
1116
1212
  return;
1117
1213
  }
1118
- const client = makeClient({ apiUrl: cfg.apiUrl, apiToken: cfg.apiToken, bank: bankId });
1214
+ const client = makeClient({
1215
+ apiUrl: cfg.apiUrl,
1216
+ apiToken: cfg.apiToken,
1217
+ bank: bankId,
1218
+ maxParallelRetains: cfg.maxParallelRetains
1219
+ });
1119
1220
  const cacheFile = sessionCacheFile(spec.harness, sessionId || "no-session");
1120
- if (cfg.autoSeed !== false && !existsSync(cacheFile)) {
1221
+ if (cfg.autoSeed !== false && !existsSync2(cacheFile)) {
1121
1222
  startBackgroundSeed(cwd, { limit: cfg.seedLimit, harness: spec.harness });
1122
1223
  }
1123
1224
  const output = await buildHookOutput({ harness: spec.harness, prompt, cfg, client, cacheFile });
@@ -1252,13 +1353,13 @@ import { execFileSync as execFileSync4 } from "child_process";
1252
1353
 
1253
1354
  // src/core/survey.ts
1254
1355
  import { spawn as realSpawn3 } from "child_process";
1255
- import { accessSync, constants, existsSync as existsSync2 } from "fs";
1356
+ import { accessSync, constants, existsSync as existsSync3 } from "fs";
1256
1357
  import { homedir as homedir3 } from "os";
1257
1358
  import { delimiter, dirname as dirname6, join as join7 } from "path";
1258
1359
  import { fileURLToPath as fileURLToPath3 } from "url";
1259
1360
 
1260
1361
  // src/core/skill-sync.ts
1261
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
1362
+ import { cpSync, existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
1262
1363
  import { homedir as homedir4 } from "os";
1263
1364
  import { dirname as dirname7, join as join8 } from "path";
1264
1365
  import { fileURLToPath as fileURLToPath4 } from "url";
@@ -1393,14 +1494,14 @@ function readCopilotTranscript(path) {
1393
1494
  }
1394
1495
 
1395
1496
  // src/core/transcript-grok.ts
1396
- import { existsSync as existsSync4, readFileSync as readFileSync7, readdirSync } from "fs";
1497
+ import { existsSync as existsSync5, readFileSync as readFileSync7, readdirSync } from "fs";
1397
1498
  import { homedir as homedir5 } from "os";
1398
1499
  import { join as join9 } from "path";
1399
1500
  var CHAT_HISTORY = "chat_history.jsonl";
1400
1501
  function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME || join9(homedir5(), ".grok")) {
1401
1502
  const sessionsDir = join9(grokHome, "sessions");
1402
1503
  const direct = join9(sessionsDir, encodeURIComponent(cwd), sessionId, CHAT_HISTORY);
1403
- if (existsSync4(direct)) return direct;
1504
+ if (existsSync5(direct)) return direct;
1404
1505
  try {
1405
1506
  for (const candidate of readdirSync(sessionsDir)) {
1406
1507
  const directory = join9(sessionsDir, candidate);
@@ -1440,7 +1541,7 @@ function readGrokTranscript(path) {
1440
1541
  }
1441
1542
 
1442
1543
  // src/core/transcript-devin.ts
1443
- import { existsSync as existsSync5 } from "fs";
1544
+ import { existsSync as existsSync6 } from "fs";
1444
1545
  import { createRequire } from "module";
1445
1546
  import { homedir as homedir6 } from "os";
1446
1547
  import { join as join10 } from "path";
@@ -1482,7 +1583,7 @@ function readDevinTranscript(sessionId, dbPath = devinSessionDb()) {
1482
1583
  diag("devin-cli", "sqlite_unavailable", { node: process.version, dbPath });
1483
1584
  return [];
1484
1585
  }
1485
- if (!existsSync5(dbPath)) {
1586
+ if (!existsSync6(dbPath)) {
1486
1587
  diag("devin-cli", "session_db_missing", { dbPath });
1487
1588
  return [];
1488
1589
  }