@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.
package/dist/kilo.js CHANGED
@@ -9,6 +9,7 @@ import { posix, win32 } from "path";
9
9
 
10
10
  // src/core/bank.ts
11
11
  import { execFileSync } from "child_process";
12
+ import { existsSync } from "fs";
12
13
  import { homedir } from "os";
13
14
  import { basename, dirname, join, normalize, sep } from "path";
14
15
 
@@ -47,25 +48,59 @@ function getProjectRootFromGit(directory) {
47
48
  function projectNameOf(directory) {
48
49
  return gitProjectName(directory, true);
49
50
  }
51
+ var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
52
+ function nearestExistingDir(directory) {
53
+ let current2 = directory;
54
+ while (current2) {
55
+ if (existsSync(current2)) return current2;
56
+ const parent = dirname(current2);
57
+ if (parent === current2) return "";
58
+ current2 = parent;
59
+ }
60
+ return "";
61
+ }
62
+ function dirName(directory) {
63
+ return directory && basename(directory) || "unknown";
64
+ }
50
65
  function gitProjectName(directory, resolveWorktrees) {
51
66
  if (resolveWorktrees) {
52
- const root = getProjectRootFromGit(directory);
53
- if (root) return basename(root);
67
+ const candidates = [
68
+ nearestExistingDir(directory),
69
+ ...PROJECT_ROOT_ENV.map((v) => process.env[v] || "")
70
+ ];
71
+ for (const candidate of candidates) {
72
+ const root = candidate ? getProjectRootFromGit(candidate) : null;
73
+ if (root) return basename(root);
74
+ }
54
75
  }
55
- return directory ? basename(directory) : "unknown";
76
+ return dirName(directory);
77
+ }
78
+ function configuredDir(dir) {
79
+ const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
80
+ return normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
81
+ }
82
+ function isWithin(directory, configured) {
83
+ return directory === configured || directory.startsWith(configured + sep);
56
84
  }
57
85
  function mapLookup(map3, directory) {
58
86
  const cwd = normalize(directory);
59
87
  let best;
60
88
  for (const [dir, bank] of Object.entries(map3)) {
61
- const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
62
- const p = normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
63
- if (cwd === p || cwd.startsWith(p + sep)) {
89
+ const p = configuredDir(dir);
90
+ if (isWithin(cwd, p)) {
64
91
  if (!best || p.length > best.len) best = { len: p.length, bank };
65
92
  }
66
93
  }
67
94
  return best?.bank;
68
95
  }
96
+ function isOptedIn(config3, directory) {
97
+ if (!config3.optInOnly) return true;
98
+ if (!directory) return false;
99
+ const cwd = normalize(directory);
100
+ if ((config3.optInPaths ?? []).some((dir) => dir && isWithin(cwd, configuredDir(dir))))
101
+ return true;
102
+ return Boolean(config3.mapPathToBank && mapLookup(config3.mapPathToBank, directory));
103
+ }
69
104
  function deriveBankId(config3, directory, harness = "coding") {
70
105
  const mapped = directory && config3.mapPathToBank ? mapLookup(config3.mapPathToBank, directory) : void 0;
71
106
  if (mapped) return mapped;
@@ -73,7 +108,7 @@ function deriveBankId(config3, directory, harness = "coding") {
73
108
  if (!dynamic) return config3.bankId || DEFAULT_BANK_NAME;
74
109
  const resolvers = {
75
110
  harness: () => harness,
76
- project: () => directory ? basename(directory) : "unknown",
111
+ project: () => dirName(directory),
77
112
  gitProject: () => gitProjectName(directory, config3.resolveWorktrees ?? true),
78
113
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
79
114
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -143,11 +178,14 @@ function resolveConfig(raw = {}) {
143
178
  bankIdTemplate: raw.bankIdTemplate,
144
179
  mapPathToBank: raw.mapPathToBank,
145
180
  resolveWorktrees: raw.resolveWorktrees,
181
+ optInOnly: raw.optInOnly ?? false,
182
+ // Same shape as retainTags: a config typo must not become a path that silently approves nothing.
183
+ optInPaths: Array.isArray(raw.optInPaths) ? raw.optInPaths.filter((p) => typeof p === "string" && p.trim() !== "") : [],
146
184
  harness: raw.harness ?? "opencode",
147
185
  disabled: raw.disabled ?? false,
148
186
  retainSessions: raw.retainSessions ?? true,
149
187
  // opencode: write back by default (parity with hook-harness Stop)
150
- retainEveryTurns: raw.retainEveryTurns || 1,
188
+ maxParallelRetains: raw.maxParallelRetains || 10,
151
189
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
152
190
  autoReflect: raw.autoReflect ?? true,
153
191
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
@@ -203,10 +241,12 @@ var ENV_KEYS = {
203
241
  dynamicBankId: "HINDSIGHT_DYNAMIC_BANK_ID",
204
242
  bankIdTemplate: "HINDSIGHT_BANK_ID_TEMPLATE",
205
243
  resolveWorktrees: "HINDSIGHT_RESOLVE_WORKTREES",
244
+ optInOnly: "HINDSIGHT_OPT_IN_ONLY",
245
+ optInPaths: "HINDSIGHT_OPT_IN_PATHS",
206
246
  harness: "HINDSIGHT_HARNESS",
207
247
  disabled: "HINDSIGHT_DISABLED",
208
248
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
209
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
249
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
210
250
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
211
251
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
212
252
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
@@ -225,17 +265,18 @@ var ENV_KEYS = {
225
265
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
226
266
  "dynamicBankId",
227
267
  "resolveWorktrees",
268
+ "optInOnly",
228
269
  "disabled",
229
270
  "retainSessions",
230
271
  "autoReflect",
231
272
  "autoSeed",
232
273
  "codebaseSurvey"
233
274
  ]);
234
- var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
275
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags", "optInPaths"]);
235
276
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
236
277
  "apiPort",
237
278
  "daemonIdleTimeout",
238
- "retainEveryTurns",
279
+ "maxParallelRetains",
239
280
  "reflectTimeoutMs",
240
281
  "pageRefreshEveryTurns",
241
282
  "seedLimit",
@@ -275,9 +316,15 @@ var BANK_OVERRIDE_EXCLUDED = [
275
316
  "mapPathToBank",
276
317
  "dynamicBankId",
277
318
  "resolveWorktrees",
319
+ // Approval is decided BEFORE the bank is resolved, so a `banks.<id>` section naming these could
320
+ // only ever arrive too late to matter — strip them rather than let them read as effective.
321
+ "optInOnly",
322
+ "optInPaths",
278
323
  "harness"
279
324
  ];
280
- function applyBankConfig(cfg, resolvedId) {
325
+ function applyBankConfig(cfg, resolvedId, directory) {
326
+ if (directory !== void 0 && !isOptedIn(cfg, directory))
327
+ return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
281
328
  const section = cfg.banks[resolvedId];
282
329
  if (!section) return { cfg, bankId: resolvedId };
283
330
  const safe = { ...section };
@@ -474,9 +521,40 @@ function semverGte(version3, min) {
474
521
  }
475
522
  return true;
476
523
  }
524
+ async function pool(items, n, fn, onError, onProgress) {
525
+ let i = 0, done = 0;
526
+ async function worker() {
527
+ while (i < items.length) {
528
+ const idx = i++;
529
+ try {
530
+ await fn(items[idx], idx);
531
+ } catch (e) {
532
+ onError?.(idx, e);
533
+ }
534
+ onProgress?.(++done, items.length);
535
+ }
536
+ }
537
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
538
+ }
477
539
 
478
540
  // src/core/hindsight.ts
479
541
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
542
+ var RateLimitedError = class extends Error {
543
+ constructor(retryAfterMs2) {
544
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
545
+ this.retryAfterMs = retryAfterMs2;
546
+ this.name = "RateLimitedError";
547
+ }
548
+ retryAfterMs;
549
+ code = "rate_limited";
550
+ };
551
+ function retryAfterMs(header) {
552
+ if (!header) return 0;
553
+ const secs = Number(header.trim());
554
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
555
+ const at = Date.parse(header);
556
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
557
+ }
480
558
  var KnowledgePagesUnavailableError = class extends Error {
481
559
  code = "knowledge_pages_unavailable";
482
560
  constructor() {
@@ -485,6 +563,10 @@ var KnowledgePagesUnavailableError = class extends Error {
485
563
  }
486
564
  };
487
565
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
566
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
567
+ var POLL_CYCLE_MS = 5e3;
568
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
569
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
488
570
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
489
571
  var HindsightClient = class {
490
572
  apiUrl;
@@ -497,12 +579,14 @@ var HindsightClient = class {
497
579
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
498
580
  idempotentRetain;
499
581
  log;
582
+ maxParallelRetains;
500
583
  constructor(o) {
501
584
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
502
585
  this.apiToken = o.apiToken;
503
586
  this.bank = o.bank;
504
587
  this.log = o.log ?? (() => {
505
588
  });
589
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
506
590
  }
507
591
  headers() {
508
592
  const h = { "Content-Type": "application/json" };
@@ -520,6 +604,8 @@ var HindsightClient = class {
520
604
  body: body ? JSON.stringify(body) : void 0,
521
605
  signal: AbortSignal.timeout(15e3)
522
606
  });
607
+ if (r.status === 429 && !tolerate.includes(429))
608
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
523
609
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
524
610
  throw new Error(`${method} ${url3} -> ${r.status} ${await r.text()}`);
525
611
  return r;
@@ -651,7 +737,14 @@ var HindsightClient = class {
651
737
  return 0;
652
738
  }
653
739
  }
654
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
740
+ /**
741
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
742
+ *
743
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
744
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
745
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
746
+ * of hammering the next cycle 5s later.
747
+ */
655
748
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
656
749
  if (!ids.length) return;
657
750
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -659,23 +752,29 @@ var HindsightClient = class {
659
752
  const pending = new Set(ids);
660
753
  let failed = 0;
661
754
  while (pending.size && Date.now() - start < maxMs) {
662
- await Promise.all(
663
- [...pending].map(async (id) => {
664
- try {
665
- const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
666
- if (!r.ok) return;
667
- const st = ((await r.json()).status || "").toLowerCase();
668
- if (TERMINAL.has(st)) {
669
- pending.delete(id);
670
- if (st !== "completed") failed++;
671
- }
672
- } catch {
755
+ let backoffMs = POLL_CYCLE_MS;
756
+ await pool([...pending], this.maxParallelRetains, async (id) => {
757
+ try {
758
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
759
+ if (r.status === 429) {
760
+ backoffMs = Math.min(
761
+ RETRY_AFTER_CEILING_MS,
762
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
763
+ );
764
+ return;
673
765
  }
674
- })
675
- );
766
+ if (!r.ok) return;
767
+ const st = ((await r.json()).status || "").toLowerCase();
768
+ if (TERMINAL.has(st)) {
769
+ pending.delete(id);
770
+ if (st !== "completed") failed++;
771
+ }
772
+ } catch {
773
+ }
774
+ });
676
775
  if (pending.size) {
677
776
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
678
- await sleep(5e3);
777
+ await sleep(backoffMs);
679
778
  }
680
779
  }
681
780
  this.log(
@@ -875,13 +974,20 @@ var HindsightClient = class {
875
974
  const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
876
975
  const content = `${verb}: ${args.title}. ${args.summary}`;
877
976
  const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
878
- await this.retain(
879
- content,
880
- "initiative marker",
881
- markerId,
882
- ["knowledge:feature-work", `relatedPageId:${pageId}`],
883
- "document"
884
- );
977
+ const tags = [
978
+ .../* @__PURE__ */ new Set([
979
+ ...args.stamp?.tags ?? [],
980
+ "knowledge:feature-work",
981
+ `relatedPageId:${pageId}`
982
+ ])
983
+ ];
984
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
985
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
986
+ metadata: args.stamp?.metadata
987
+ });
988
+ } else {
989
+ await this.retain(content, "initiative marker", markerId, tags, "document");
990
+ }
885
991
  return { page_id: pageId };
886
992
  }
887
993
  /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
@@ -15431,7 +15537,7 @@ function date4(params) {
15431
15537
  config(en_default());
15432
15538
 
15433
15539
  // src/core/knowledge-tools.ts
15434
- import { existsSync as existsSync2 } from "fs";
15540
+ import { existsSync as existsSync3 } from "fs";
15435
15541
  import { homedir as homedir4 } from "os";
15436
15542
  import { join as join6 } from "path";
15437
15543
 
@@ -15516,7 +15622,7 @@ ${toolGuide(opts)}
15516
15622
 
15517
15623
  // src/core/survey.ts
15518
15624
  import { spawn as realSpawn2 } from "child_process";
15519
- import { accessSync, constants, existsSync } from "fs";
15625
+ import { accessSync, constants, existsSync as existsSync2 } from "fs";
15520
15626
  import { homedir as homedir3 } from "os";
15521
15627
  import { delimiter, dirname as dirname4, join as join5 } from "path";
15522
15628
  import { fileURLToPath as fileURLToPath2 } from "url";
@@ -15531,7 +15637,7 @@ function resolveClaudeBin(explicit) {
15531
15637
  if (process.env.HINDSIGHT_CLAUDE_BIN) return process.env.HINDSIGHT_CLAUDE_BIN;
15532
15638
  const nativeInstallPath = join5(homedir3(), ".claude", "local", "claude");
15533
15639
  try {
15534
- if (existsSync(nativeInstallPath)) return nativeInstallPath;
15640
+ if (existsSync2(nativeInstallPath)) return nativeInstallPath;
15535
15641
  } catch {
15536
15642
  }
15537
15643
  return "claude";
@@ -15805,7 +15911,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15805
15911
  workspace: opts.repoDir ?? process.cwd(),
15806
15912
  config: {
15807
15913
  path: configPath,
15808
- exists: existsSync2(configPath),
15914
+ exists: existsSync3(configPath),
15809
15915
  api_url: cfg.apiUrl,
15810
15916
  api_token_configured: Boolean(cfg.apiToken),
15811
15917
  disabled: cfg.disabled
@@ -15870,7 +15976,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15870
15976
  relates_to_page_id: external_exports.string().optional()
15871
15977
  },
15872
15978
  handler: guarded(
15873
- async ({ title, summary, relates_to_page_id }) => client.captureInitiative({ title, summary, relatesToPageId: relates_to_page_id })
15979
+ async ({ title, summary, relates_to_page_id }) => client.captureInitiative({
15980
+ title,
15981
+ summary,
15982
+ relatesToPageId: relates_to_page_id,
15983
+ ...opts.stampFor ? { stamp: opts.stampFor() } : {}
15984
+ })
15874
15985
  )
15875
15986
  },
15876
15987
  {
@@ -15879,13 +15990,24 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15879
15990
  inputSchema: { title: external_exports.string(), content: external_exports.string() },
15880
15991
  handler: guarded(async ({ title, content }) => {
15881
15992
  const docId = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "doc";
15993
+ const stamp = opts.stampFor?.();
15994
+ const metadata = {
15995
+ ...stamp?.metadata,
15996
+ ...opts.harness ? { harness: opts.harness } : {}
15997
+ };
15882
15998
  await client.retain(
15883
15999
  content,
15884
16000
  "ingested document",
15885
16001
  docId,
15886
- ["source:upload", ...opts.harness ? [`harness:${opts.harness}`] : []],
16002
+ [
16003
+ .../* @__PURE__ */ new Set([
16004
+ ...stamp?.tags ?? [],
16005
+ "source:upload",
16006
+ ...opts.harness ? [`harness:${opts.harness}`] : []
16007
+ ])
16008
+ ],
15887
16009
  "document",
15888
- { metadata: opts.harness ? { harness: opts.harness } : void 0 }
16010
+ Object.keys(metadata).length ? { metadata } : {}
15889
16011
  );
15890
16012
  return { ok: true, doc_id: docId };
15891
16013
  })
@@ -15952,6 +16074,23 @@ async function supportsAppend(client) {
15952
16074
  return false;
15953
16075
  }
15954
16076
  }
16077
+ var RETAIN_RETRY_ATTEMPTS = 2;
16078
+ var RETAIN_RETRY_BUDGET_MS = 6e3;
16079
+ async function submitWithRetry(send, isStillNewest) {
16080
+ let spent = 0;
16081
+ for (let attempt = 0; ; attempt++) {
16082
+ try {
16083
+ return await send();
16084
+ } catch (e) {
16085
+ const limited = e instanceof RateLimitedError;
16086
+ if (!limited || attempt >= RETAIN_RETRY_ATTEMPTS || !isStillNewest()) throw e;
16087
+ const wait = e.retryAfterMs || 1e3;
16088
+ if (wait > RETAIN_RETRY_BUDGET_MS - spent) throw e;
16089
+ spent += wait;
16090
+ await sleep(wait);
16091
+ }
16092
+ }
16093
+ }
15955
16094
  var writeBacks = /* @__PURE__ */ new WeakMap();
15956
16095
  function serialize(cursors, sessionId, write2) {
15957
16096
  const perSession = writeBacks.get(cursors) ?? /* @__PURE__ */ new Map();
@@ -15986,37 +16125,46 @@ async function writeSession(client, sessionId, turns, startTs, harness, stamp, c
15986
16125
  bank: client.bank
15987
16126
  };
15988
16127
  cursors?.write(sessionId, { ...next, dirty: true });
15989
- await client.retain(
15990
- content,
15991
- "coding agent session",
15992
- refId,
15993
- // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
15994
- // the documents list filters and draws its agent logo from, so a template cannot displace them.
15995
- [
15996
- .../* @__PURE__ */ new Set([
15997
- ...stamp?.tags ?? [],
15998
- "source:chat",
15999
- ...harness ? [`harness:${harness}`] : []
16000
- ])
16001
- ],
16002
- "conversation",
16003
- {
16004
- timestamp: startTs,
16005
- updateMode: plan.mode === "append" ? "append" : void 0,
16006
- // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
16007
- // the original operation instead of extracting (or appending) twice.
16008
- operationId: uuidV5(`${client.bank}
16128
+ const claimed = { ...next, dirty: true };
16129
+ await submitWithRetry(
16130
+ () => client.retain(
16131
+ content,
16132
+ "coding agent session",
16133
+ refId,
16134
+ // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
16135
+ // the documents list filters and draws its agent logo from, so a template cannot displace them.
16136
+ [
16137
+ .../* @__PURE__ */ new Set([
16138
+ ...stamp?.tags ?? [],
16139
+ "source:chat",
16140
+ ...harness ? [`harness:${harness}`] : []
16141
+ ])
16142
+ ],
16143
+ "conversation",
16144
+ {
16145
+ timestamp: startTs,
16146
+ updateMode: plan.mode === "append" ? "append" : void 0,
16147
+ // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
16148
+ // the original operation instead of extracting (or appending) twice.
16149
+ operationId: uuidV5(`${client.bank}
16009
16150
  ${refId}
16010
16151
  ${plan.mode}
16011
16152
  ${content}`),
16012
- metadata: {
16013
- ...stamp?.metadata,
16014
- // configured first: the built-ins below win on any key collision
16015
- source: "chat",
16016
- session_id: sessionId,
16017
- ref_id: refId,
16018
- ...harness ? { harness } : {}
16019
- }
16153
+ metadata: {
16154
+ ...stamp?.metadata,
16155
+ // configured first: the built-ins below win on any key collision
16156
+ source: "chat",
16157
+ session_id: sessionId,
16158
+ ref_id: refId,
16159
+ ...harness ? { harness } : {}
16160
+ }
16161
+ }
16162
+ ),
16163
+ // Still ours to retry only while the cursor holds the claim we wrote above.
16164
+ () => {
16165
+ if (!cursors) return true;
16166
+ const now = cursors.read(sessionId);
16167
+ return now?.turns === claimed.turns && now?.fingerprint === claimed.fingerprint;
16020
16168
  }
16021
16169
  );
16022
16170
  cursors?.write(sessionId, next);
@@ -16033,7 +16181,7 @@ function resolversFor(ctx) {
16033
16181
  project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
16034
16182
  harness: () => ctx.harness,
16035
16183
  bankId: () => ctx.bankId,
16036
- sessionId: () => ctx.sessionId,
16184
+ sessionId: () => ctx.sessionId ?? "unknown",
16037
16185
  timestamp: () => (/* @__PURE__ */ new Date()).toISOString(),
16038
16186
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
16039
16187
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -16073,7 +16221,7 @@ function buildRetainStamp(cfg, ctx) {
16073
16221
  import { readFileSync as readFileSync4 } from "fs";
16074
16222
 
16075
16223
  // src/core/skill-sync.ts
16076
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
16224
+ import { cpSync, existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
16077
16225
  import { homedir as homedir5 } from "os";
16078
16226
  import { dirname as dirname5, join as join7 } from "path";
16079
16227
  import { fileURLToPath as fileURLToPath3 } from "url";
@@ -16098,7 +16246,7 @@ function brandWord() {
16098
16246
  }
16099
16247
 
16100
16248
  // src/core/session-cache.ts
16101
- import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync } from "fs";
16249
+ import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync, rmSync, writeFileSync } from "fs";
16102
16250
  import { tmpdir as tmpdir2 } from "os";
16103
16251
  import { dirname as dirname7, join as join9 } from "path";
16104
16252
  function sessionCacheFile(harness, sessionId) {
@@ -16111,10 +16259,23 @@ function readSessionCache(cacheFile) {
16111
16259
  return {};
16112
16260
  }
16113
16261
  }
16262
+ function writeFileAtomic(path, body) {
16263
+ mkdirSync2(dirname7(path), { recursive: true });
16264
+ const tmp = `${path}.${process.pid}.tmp`;
16265
+ try {
16266
+ writeFileSync(tmp, body);
16267
+ renameSync(tmp, path);
16268
+ } catch (e) {
16269
+ try {
16270
+ rmSync(tmp, { force: true });
16271
+ } catch {
16272
+ }
16273
+ throw e;
16274
+ }
16275
+ }
16114
16276
  function writeSessionCache(cacheFile, cache) {
16115
16277
  try {
16116
- mkdirSync2(dirname7(cacheFile), { recursive: true });
16117
- writeFileSync(cacheFile, JSON.stringify(cache));
16278
+ writeFileAtomic(cacheFile, JSON.stringify(cache));
16118
16279
  } catch {
16119
16280
  }
16120
16281
  }
@@ -16157,20 +16318,25 @@ async function buildSessionStartContext(args) {
16157
16318
  const startSurvey = args.startSurvey ?? startCodebaseSurvey;
16158
16319
  const resolveHeadSha = args.headSha ?? gitHeadSha;
16159
16320
  const countCommitsSince = args.commitsSince ?? commitsSince;
16321
+ const retainStamp = () => buildRetainStamp(cfg, { directory: cwd, harness, bankId });
16160
16322
  const SURVEY_BASELINE_TAG = "source:survey-baseline";
16161
16323
  const SURVEY_BASELINE_PREFIX = "survey-baseline:";
16162
16324
  const recordSurveyBaseline = (sha) => {
16163
16325
  if (!client.retain) return;
16164
16326
  try {
16165
- void Promise.resolve(
16166
- client.retain(
16167
- `\u{1F6F0}\uFE0F Hindsight is researching this codebase \u2014 survey started at commit ${sha.slice(0, 12)}. (Internal marker: no memories are extracted from this document.)`,
16168
- "hindsight codebase-survey baseline",
16169
- `${SURVEY_BASELINE_PREFIX}${sha}`,
16170
- [SURVEY_BASELINE_TAG],
16171
- "survey"
16172
- )
16173
- ).catch(() => {
16327
+ const stamp = retainStamp();
16328
+ const content = `\u{1F6F0}\uFE0F Hindsight is researching this codebase \u2014 survey started at commit ${sha.slice(0, 12)}. (Internal marker: no memories are extracted from this document.)`;
16329
+ const tags = [.../* @__PURE__ */ new Set([...stamp.tags, SURVEY_BASELINE_TAG])];
16330
+ const retained = client.retain(
16331
+ content,
16332
+ "hindsight codebase-survey baseline",
16333
+ `${SURVEY_BASELINE_PREFIX}${sha}`,
16334
+ tags,
16335
+ "survey",
16336
+ // `retain` only sets metadata when it is truthy, so an empty stamp sends none.
16337
+ { metadata: Object.keys(stamp.metadata).length ? stamp.metadata : void 0 }
16338
+ );
16339
+ void Promise.resolve(retained).catch(() => {
16174
16340
  });
16175
16341
  } catch {
16176
16342
  }
@@ -16262,7 +16428,7 @@ async function buildSessionStartContext(args) {
16262
16428
  }
16263
16429
 
16264
16430
  // src/core/hook.ts
16265
- import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
16431
+ import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
16266
16432
 
16267
16433
  // src/core/inject.ts
16268
16434
  function buildReflectQuery(prompt) {
@@ -16309,7 +16475,10 @@ async function buildHookOutput(args) {
16309
16475
  const t0 = Date.now();
16310
16476
  try {
16311
16477
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
16312
- budget: "high",
16478
+ // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
16479
+ // supported default for bounded reflect calls; callers that explicitly invoke the MCP
16480
+ // tool still get the deeper high-budget path.
16481
+ budget: "low",
16313
16482
  timeoutMs: Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS)
16314
16483
  });
16315
16484
  diag(harness, reflectAnswer ? "reflect_ok" : "reflect_empty", {
@@ -16418,7 +16587,15 @@ var RuntimeCore = class {
16418
16587
  }
16419
16588
  /** The hindsight_* knowledge + recall tools, bound to this bank, for the harness to register natively. */
16420
16589
  toolSpecs() {
16421
- return buildKnowledgeTools(this.client, this.bankId, { harness: this.harness });
16590
+ return buildKnowledgeTools(this.client, this.bankId, {
16591
+ repoDir: this.projectDir,
16592
+ harness: this.harness,
16593
+ stampFor: () => buildRetainStamp(this.cfg, {
16594
+ directory: this.projectDir,
16595
+ harness: this.harness,
16596
+ bankId: this.bankId
16597
+ })
16598
+ });
16422
16599
  }
16423
16600
  get writeBackEnabled() {
16424
16601
  return this.cfg.retainSessions;
@@ -16495,19 +16672,22 @@ var RuntimeCore = class {
16495
16672
  return keyed ?? this.lastInjection ?? void 0;
16496
16673
  }
16497
16674
  /**
16498
- * Full normalized transcript (rich: user/assistant text + tool calls/outputs): upsert every N user
16499
- * turns when enabled. On by default for persistent-plugin hosts (parity with hook-harness Stop write-back),
16500
- * so opencode sessions compound into memory; a user can opt out with `retainSessions: false`.
16675
+ * Full normalized transcript (rich: user/assistant text + tool calls/outputs): upsert every turn
16676
+ * when enabled. On by default for persistent-plugin hosts (parity with hook-harness Stop
16677
+ * write-back), so opencode sessions compound into memory; opt out with `retainSessions: false`.
16678
+ *
16679
+ * There is deliberately no client-side cadence. Batching write-backs meant holding turns in a
16680
+ * process the host can close at any moment, with no reliable signal on the way out — the flush a
16681
+ * cadence needs would have to ride a session-end hook, and those are cancelled at shutdown. The
16682
+ * server coalesces instead: queued retains for one document fold into a single execution
16683
+ * (`engine.retain.fold`), so submitting every turn costs one extraction, not one per turn, and
16684
+ * nothing is ever held somewhere it can be lost.
16501
16685
  */
16502
16686
  async onTranscript(sessionId, turns) {
16503
16687
  if (process.env.HINDSIGHT_DISABLE_HOOKS) return;
16504
16688
  if (!this.writeBackEnabled || !sessionId || !turns.length) return;
16505
- const users = turns.filter((t) => t.role === "user").length;
16506
16689
  const st = this.stateFor(sessionId);
16507
- if (users - st.retainedUsers >= this.cfg.retainEveryTurns) {
16508
- st.retainedUsers = users;
16509
- this.retain(sessionId, turns, st.startTs);
16510
- }
16690
+ this.retain(sessionId, turns, st.startTs);
16511
16691
  }
16512
16692
  /**
16513
16693
  * Session went idle — the assistant has finished replying.
@@ -16538,13 +16718,12 @@ var RuntimeCore = class {
16538
16718
  const st = this.stateFor(sessionId);
16539
16719
  if (turns.length <= st.retainedTurns) return;
16540
16720
  st.retainedTurns = turns.length;
16541
- st.retainedUsers = turns.filter((t) => t.role === "user").length;
16542
16721
  this.retain(sessionId, turns, st.startTs, "idle");
16543
16722
  }
16544
16723
  stateFor(sessionId) {
16545
16724
  let st = this.sessionState.get(sessionId);
16546
16725
  if (!st) {
16547
- st = { startTs: (/* @__PURE__ */ new Date()).toISOString(), retainedUsers: 0, retainedTurns: 0 };
16726
+ st = { startTs: (/* @__PURE__ */ new Date()).toISOString(), retainedTurns: 0 };
16548
16727
  this.sessionState.set(sessionId, st);
16549
16728
  }
16550
16729
  return st;
@@ -29153,14 +29332,19 @@ function createPluginEntry(harness) {
29153
29332
  const projectDir = resolveProjectDirectory(input);
29154
29333
  let cfg = loadConfig({ harness });
29155
29334
  if (cfg.disabled) return {};
29156
- const resolved = applyBankConfig(cfg, deriveBankId(cfg, projectDir || process.cwd(), harness));
29335
+ const resolved = applyBankConfig(
29336
+ cfg,
29337
+ deriveBankId(cfg, projectDir || process.cwd(), harness),
29338
+ projectDir || process.cwd()
29339
+ );
29157
29340
  cfg = resolved.cfg;
29158
29341
  const bankId = resolved.bankId;
29159
29342
  if (cfg.disabled) return {};
29160
29343
  const client = new HindsightClient({
29161
29344
  apiUrl: cfg.apiUrl,
29162
29345
  apiToken: cfg.apiToken,
29163
- bank: bankId
29346
+ bank: bankId,
29347
+ maxParallelRetains: cfg.maxParallelRetains
29164
29348
  });
29165
29349
  const core = new RuntimeCore(client, bankId, cfg, harness, projectDir || process.cwd());
29166
29350
  const oc = input?.client;