@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.
package/dist/cline.js CHANGED
@@ -70,7 +70,7 @@ function resolveConfig(raw = {}) {
70
70
  disabled: raw.disabled ?? false,
71
71
  retainSessions: raw.retainSessions ?? true,
72
72
  // opencode: write back by default (parity with hook-harness Stop)
73
- retainEveryTurns: raw.retainEveryTurns || 1,
73
+ maxParallelRetains: raw.maxParallelRetains || 10,
74
74
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
75
75
  autoReflect: raw.autoReflect ?? true,
76
76
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
@@ -129,7 +129,7 @@ var ENV_KEYS = {
129
129
  harness: "HINDSIGHT_HARNESS",
130
130
  disabled: "HINDSIGHT_DISABLED",
131
131
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
132
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
132
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
133
133
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
134
134
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
135
135
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
@@ -158,7 +158,7 @@ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
158
158
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
159
159
  "apiPort",
160
160
  "daemonIdleTimeout",
161
- "retainEveryTurns",
161
+ "maxParallelRetains",
162
162
  "reflectTimeoutMs",
163
163
  "pageRefreshEveryTurns",
164
164
  "seedLimit",
@@ -222,6 +222,7 @@ function resolvePartial(cfg, patch) {
222
222
 
223
223
  // src/core/bank.ts
224
224
  import { execFileSync } from "child_process";
225
+ import { existsSync } from "fs";
225
226
  import { homedir as homedir2 } from "os";
226
227
  import { basename, dirname as dirname2, join as join3, normalize, sep } from "path";
227
228
 
@@ -260,12 +261,32 @@ function getProjectRootFromGit(directory) {
260
261
  function projectNameOf(directory) {
261
262
  return gitProjectName(directory, true);
262
263
  }
264
+ var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
265
+ function nearestExistingDir(directory) {
266
+ let current2 = directory;
267
+ while (current2) {
268
+ if (existsSync(current2)) return current2;
269
+ const parent = dirname2(current2);
270
+ if (parent === current2) return "";
271
+ current2 = parent;
272
+ }
273
+ return "";
274
+ }
275
+ function dirName(directory) {
276
+ return directory && basename(directory) || "unknown";
277
+ }
263
278
  function gitProjectName(directory, resolveWorktrees) {
264
279
  if (resolveWorktrees) {
265
- const root = getProjectRootFromGit(directory);
266
- if (root) return basename(root);
280
+ const candidates = [
281
+ nearestExistingDir(directory),
282
+ ...PROJECT_ROOT_ENV.map((v) => process.env[v] || "")
283
+ ];
284
+ for (const candidate of candidates) {
285
+ const root = candidate ? getProjectRootFromGit(candidate) : null;
286
+ if (root) return basename(root);
287
+ }
267
288
  }
268
- return directory ? basename(directory) : "unknown";
289
+ return dirName(directory);
269
290
  }
270
291
  function mapLookup(map2, directory) {
271
292
  const cwd = normalize(directory);
@@ -286,7 +307,7 @@ function deriveBankId(config2, directory, harness = "coding") {
286
307
  if (!dynamic) return config2.bankId || DEFAULT_BANK_NAME;
287
308
  const resolvers = {
288
309
  harness: () => harness,
289
- project: () => directory ? basename(directory) : "unknown",
310
+ project: () => dirName(directory),
290
311
  gitProject: () => gitProjectName(directory, config2.resolveWorktrees ?? true),
291
312
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
292
313
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -438,9 +459,40 @@ function semverGte(version2, min) {
438
459
  }
439
460
  return true;
440
461
  }
462
+ async function pool(items, n, fn, onError, onProgress) {
463
+ let i = 0, done = 0;
464
+ async function worker() {
465
+ while (i < items.length) {
466
+ const idx = i++;
467
+ try {
468
+ await fn(items[idx], idx);
469
+ } catch (e) {
470
+ onError?.(idx, e);
471
+ }
472
+ onProgress?.(++done, items.length);
473
+ }
474
+ }
475
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
476
+ }
441
477
 
442
478
  // src/core/hindsight.ts
443
479
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
480
+ var RateLimitedError = class extends Error {
481
+ constructor(retryAfterMs2) {
482
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
483
+ this.retryAfterMs = retryAfterMs2;
484
+ this.name = "RateLimitedError";
485
+ }
486
+ retryAfterMs;
487
+ code = "rate_limited";
488
+ };
489
+ function retryAfterMs(header) {
490
+ if (!header) return 0;
491
+ const secs = Number(header.trim());
492
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
493
+ const at = Date.parse(header);
494
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
495
+ }
444
496
  var KnowledgePagesUnavailableError = class extends Error {
445
497
  code = "knowledge_pages_unavailable";
446
498
  constructor() {
@@ -449,6 +501,10 @@ var KnowledgePagesUnavailableError = class extends Error {
449
501
  }
450
502
  };
451
503
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
504
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
505
+ var POLL_CYCLE_MS = 5e3;
506
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
507
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
452
508
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
453
509
  var HindsightClient = class {
454
510
  apiUrl;
@@ -461,12 +517,14 @@ var HindsightClient = class {
461
517
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
462
518
  idempotentRetain;
463
519
  log;
520
+ maxParallelRetains;
464
521
  constructor(o) {
465
522
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
466
523
  this.apiToken = o.apiToken;
467
524
  this.bank = o.bank;
468
525
  this.log = o.log ?? (() => {
469
526
  });
527
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
470
528
  }
471
529
  headers() {
472
530
  const h = { "Content-Type": "application/json" };
@@ -484,6 +542,8 @@ var HindsightClient = class {
484
542
  body: body ? JSON.stringify(body) : void 0,
485
543
  signal: AbortSignal.timeout(15e3)
486
544
  });
545
+ if (r.status === 429 && !tolerate.includes(429))
546
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
487
547
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
488
548
  throw new Error(`${method} ${url2} -> ${r.status} ${await r.text()}`);
489
549
  return r;
@@ -615,7 +675,14 @@ var HindsightClient = class {
615
675
  return 0;
616
676
  }
617
677
  }
618
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
678
+ /**
679
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
680
+ *
681
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
682
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
683
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
684
+ * of hammering the next cycle 5s later.
685
+ */
619
686
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
620
687
  if (!ids.length) return;
621
688
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -623,23 +690,29 @@ var HindsightClient = class {
623
690
  const pending = new Set(ids);
624
691
  let failed = 0;
625
692
  while (pending.size && Date.now() - start < maxMs) {
626
- await Promise.all(
627
- [...pending].map(async (id) => {
628
- try {
629
- const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
630
- if (!r.ok) return;
631
- const st = ((await r.json()).status || "").toLowerCase();
632
- if (TERMINAL.has(st)) {
633
- pending.delete(id);
634
- if (st !== "completed") failed++;
635
- }
636
- } catch {
693
+ let backoffMs = POLL_CYCLE_MS;
694
+ await pool([...pending], this.maxParallelRetains, async (id) => {
695
+ try {
696
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
697
+ if (r.status === 429) {
698
+ backoffMs = Math.min(
699
+ RETRY_AFTER_CEILING_MS,
700
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
701
+ );
702
+ return;
637
703
  }
638
- })
639
- );
704
+ if (!r.ok) return;
705
+ const st = ((await r.json()).status || "").toLowerCase();
706
+ if (TERMINAL.has(st)) {
707
+ pending.delete(id);
708
+ if (st !== "completed") failed++;
709
+ }
710
+ } catch {
711
+ }
712
+ });
640
713
  if (pending.size) {
641
714
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
642
- await sleep(5e3);
715
+ await sleep(backoffMs);
643
716
  }
644
717
  }
645
718
  this.log(
@@ -839,13 +912,20 @@ var HindsightClient = class {
839
912
  const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
840
913
  const content = `${verb}: ${args.title}. ${args.summary}`;
841
914
  const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
842
- await this.retain(
843
- content,
844
- "initiative marker",
845
- markerId,
846
- ["knowledge:feature-work", `relatedPageId:${pageId}`],
847
- "document"
848
- );
915
+ const tags = [
916
+ .../* @__PURE__ */ new Set([
917
+ ...args.stamp?.tags ?? [],
918
+ "knowledge:feature-work",
919
+ `relatedPageId:${pageId}`
920
+ ])
921
+ ];
922
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
923
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
924
+ metadata: args.stamp?.metadata
925
+ });
926
+ } else {
927
+ await this.retain(content, "initiative marker", markerId, tags, "document");
928
+ }
849
929
  return { page_id: pageId };
850
930
  }
851
931
  /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
@@ -15430,7 +15510,7 @@ function date4(params) {
15430
15510
  config(en_default());
15431
15511
 
15432
15512
  // src/core/knowledge-tools.ts
15433
- import { existsSync as existsSync2 } from "fs";
15513
+ import { existsSync as existsSync3 } from "fs";
15434
15514
  import { homedir as homedir4 } from "os";
15435
15515
  import { join as join6 } from "path";
15436
15516
 
@@ -15515,7 +15595,7 @@ ${toolGuide(opts)}
15515
15595
 
15516
15596
  // src/core/survey.ts
15517
15597
  import { spawn as realSpawn2 } from "child_process";
15518
- import { accessSync, constants, existsSync } from "fs";
15598
+ import { accessSync, constants, existsSync as existsSync2 } from "fs";
15519
15599
  import { homedir as homedir3 } from "os";
15520
15600
  import { delimiter, dirname as dirname4, join as join5 } from "path";
15521
15601
  import { fileURLToPath as fileURLToPath2 } from "url";
@@ -15530,7 +15610,7 @@ function resolveClaudeBin(explicit) {
15530
15610
  if (process.env.HINDSIGHT_CLAUDE_BIN) return process.env.HINDSIGHT_CLAUDE_BIN;
15531
15611
  const nativeInstallPath = join5(homedir3(), ".claude", "local", "claude");
15532
15612
  try {
15533
- if (existsSync(nativeInstallPath)) return nativeInstallPath;
15613
+ if (existsSync2(nativeInstallPath)) return nativeInstallPath;
15534
15614
  } catch {
15535
15615
  }
15536
15616
  return "claude";
@@ -15804,7 +15884,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15804
15884
  workspace: opts.repoDir ?? process.cwd(),
15805
15885
  config: {
15806
15886
  path: configPath,
15807
- exists: existsSync2(configPath),
15887
+ exists: existsSync3(configPath),
15808
15888
  api_url: cfg.apiUrl,
15809
15889
  api_token_configured: Boolean(cfg.apiToken),
15810
15890
  disabled: cfg.disabled
@@ -15869,7 +15949,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15869
15949
  relates_to_page_id: external_exports.string().optional()
15870
15950
  },
15871
15951
  handler: guarded(
15872
- async ({ title, summary, relates_to_page_id }) => client.captureInitiative({ title, summary, relatesToPageId: relates_to_page_id })
15952
+ async ({ title, summary, relates_to_page_id }) => client.captureInitiative({
15953
+ title,
15954
+ summary,
15955
+ relatesToPageId: relates_to_page_id,
15956
+ ...opts.stampFor ? { stamp: opts.stampFor() } : {}
15957
+ })
15873
15958
  )
15874
15959
  },
15875
15960
  {
@@ -15878,13 +15963,24 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15878
15963
  inputSchema: { title: external_exports.string(), content: external_exports.string() },
15879
15964
  handler: guarded(async ({ title, content }) => {
15880
15965
  const docId = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "doc";
15966
+ const stamp = opts.stampFor?.();
15967
+ const metadata = {
15968
+ ...stamp?.metadata,
15969
+ ...opts.harness ? { harness: opts.harness } : {}
15970
+ };
15881
15971
  await client.retain(
15882
15972
  content,
15883
15973
  "ingested document",
15884
15974
  docId,
15885
- ["source:upload", ...opts.harness ? [`harness:${opts.harness}`] : []],
15975
+ [
15976
+ .../* @__PURE__ */ new Set([
15977
+ ...stamp?.tags ?? [],
15978
+ "source:upload",
15979
+ ...opts.harness ? [`harness:${opts.harness}`] : []
15980
+ ])
15981
+ ],
15886
15982
  "document",
15887
- { metadata: opts.harness ? { harness: opts.harness } : void 0 }
15983
+ Object.keys(metadata).length ? { metadata } : {}
15888
15984
  );
15889
15985
  return { ok: true, doc_id: docId };
15890
15986
  })
@@ -15951,6 +16047,23 @@ async function supportsAppend(client) {
15951
16047
  return false;
15952
16048
  }
15953
16049
  }
16050
+ var RETAIN_RETRY_ATTEMPTS = 2;
16051
+ var RETAIN_RETRY_BUDGET_MS = 6e3;
16052
+ async function submitWithRetry(send, isStillNewest) {
16053
+ let spent = 0;
16054
+ for (let attempt = 0; ; attempt++) {
16055
+ try {
16056
+ return await send();
16057
+ } catch (e) {
16058
+ const limited = e instanceof RateLimitedError;
16059
+ if (!limited || attempt >= RETAIN_RETRY_ATTEMPTS || !isStillNewest()) throw e;
16060
+ const wait = e.retryAfterMs || 1e3;
16061
+ if (wait > RETAIN_RETRY_BUDGET_MS - spent) throw e;
16062
+ spent += wait;
16063
+ await sleep(wait);
16064
+ }
16065
+ }
16066
+ }
15954
16067
  var writeBacks = /* @__PURE__ */ new WeakMap();
15955
16068
  function serialize(cursors, sessionId2, write2) {
15956
16069
  const perSession = writeBacks.get(cursors) ?? /* @__PURE__ */ new Map();
@@ -15985,37 +16098,46 @@ async function writeSession(client, sessionId2, turns, startTs, harness, stamp,
15985
16098
  bank: client.bank
15986
16099
  };
15987
16100
  cursors?.write(sessionId2, { ...next, dirty: true });
15988
- await client.retain(
15989
- content,
15990
- "coding agent session",
15991
- refId,
15992
- // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
15993
- // the documents list filters and draws its agent logo from, so a template cannot displace them.
15994
- [
15995
- .../* @__PURE__ */ new Set([
15996
- ...stamp?.tags ?? [],
15997
- "source:chat",
15998
- ...harness ? [`harness:${harness}`] : []
15999
- ])
16000
- ],
16001
- "conversation",
16002
- {
16003
- timestamp: startTs,
16004
- updateMode: plan.mode === "append" ? "append" : void 0,
16005
- // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
16006
- // the original operation instead of extracting (or appending) twice.
16007
- operationId: uuidV5(`${client.bank}
16101
+ const claimed = { ...next, dirty: true };
16102
+ await submitWithRetry(
16103
+ () => client.retain(
16104
+ content,
16105
+ "coding agent session",
16106
+ refId,
16107
+ // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
16108
+ // the documents list filters and draws its agent logo from, so a template cannot displace them.
16109
+ [
16110
+ .../* @__PURE__ */ new Set([
16111
+ ...stamp?.tags ?? [],
16112
+ "source:chat",
16113
+ ...harness ? [`harness:${harness}`] : []
16114
+ ])
16115
+ ],
16116
+ "conversation",
16117
+ {
16118
+ timestamp: startTs,
16119
+ updateMode: plan.mode === "append" ? "append" : void 0,
16120
+ // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
16121
+ // the original operation instead of extracting (or appending) twice.
16122
+ operationId: uuidV5(`${client.bank}
16008
16123
  ${refId}
16009
16124
  ${plan.mode}
16010
16125
  ${content}`),
16011
- metadata: {
16012
- ...stamp?.metadata,
16013
- // configured first: the built-ins below win on any key collision
16014
- source: "chat",
16015
- session_id: sessionId2,
16016
- ref_id: refId,
16017
- ...harness ? { harness } : {}
16126
+ metadata: {
16127
+ ...stamp?.metadata,
16128
+ // configured first: the built-ins below win on any key collision
16129
+ source: "chat",
16130
+ session_id: sessionId2,
16131
+ ref_id: refId,
16132
+ ...harness ? { harness } : {}
16133
+ }
16018
16134
  }
16135
+ ),
16136
+ // Still ours to retry only while the cursor holds the claim we wrote above.
16137
+ () => {
16138
+ if (!cursors) return true;
16139
+ const now = cursors.read(sessionId2);
16140
+ return now?.turns === claimed.turns && now?.fingerprint === claimed.fingerprint;
16019
16141
  }
16020
16142
  );
16021
16143
  cursors?.write(sessionId2, next);
@@ -16032,7 +16154,7 @@ function resolversFor(ctx) {
16032
16154
  project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
16033
16155
  harness: () => ctx.harness,
16034
16156
  bankId: () => ctx.bankId,
16035
- sessionId: () => ctx.sessionId,
16157
+ sessionId: () => ctx.sessionId ?? "unknown",
16036
16158
  timestamp: () => (/* @__PURE__ */ new Date()).toISOString(),
16037
16159
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
16038
16160
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -16072,7 +16194,7 @@ function buildRetainStamp(cfg, ctx) {
16072
16194
  import { readFileSync as readFileSync4 } from "fs";
16073
16195
 
16074
16196
  // src/core/skill-sync.ts
16075
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
16197
+ import { cpSync, existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
16076
16198
  import { homedir as homedir5 } from "os";
16077
16199
  import { dirname as dirname5, join as join7 } from "path";
16078
16200
  import { fileURLToPath as fileURLToPath3 } from "url";
@@ -16097,7 +16219,7 @@ function brandWord() {
16097
16219
  }
16098
16220
 
16099
16221
  // src/core/session-cache.ts
16100
- import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync } from "fs";
16222
+ import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync, rmSync, writeFileSync } from "fs";
16101
16223
  import { tmpdir as tmpdir2 } from "os";
16102
16224
  import { dirname as dirname7, join as join9 } from "path";
16103
16225
  function sessionCacheFile(harness, sessionId2) {
@@ -16110,10 +16232,23 @@ function readSessionCache(cacheFile) {
16110
16232
  return {};
16111
16233
  }
16112
16234
  }
16235
+ function writeFileAtomic(path, body) {
16236
+ mkdirSync2(dirname7(path), { recursive: true });
16237
+ const tmp = `${path}.${process.pid}.tmp`;
16238
+ try {
16239
+ writeFileSync(tmp, body);
16240
+ renameSync(tmp, path);
16241
+ } catch (e) {
16242
+ try {
16243
+ rmSync(tmp, { force: true });
16244
+ } catch {
16245
+ }
16246
+ throw e;
16247
+ }
16248
+ }
16113
16249
  function writeSessionCache(cacheFile, cache) {
16114
16250
  try {
16115
- mkdirSync2(dirname7(cacheFile), { recursive: true });
16116
- writeFileSync(cacheFile, JSON.stringify(cache));
16251
+ writeFileAtomic(cacheFile, JSON.stringify(cache));
16117
16252
  } catch {
16118
16253
  }
16119
16254
  }
@@ -16156,20 +16291,25 @@ async function buildSessionStartContext(args) {
16156
16291
  const startSurvey = args.startSurvey ?? startCodebaseSurvey;
16157
16292
  const resolveHeadSha = args.headSha ?? gitHeadSha;
16158
16293
  const countCommitsSince = args.commitsSince ?? commitsSince;
16294
+ const retainStamp = () => buildRetainStamp(cfg, { directory: cwd, harness, bankId });
16159
16295
  const SURVEY_BASELINE_TAG = "source:survey-baseline";
16160
16296
  const SURVEY_BASELINE_PREFIX = "survey-baseline:";
16161
16297
  const recordSurveyBaseline = (sha) => {
16162
16298
  if (!client.retain) return;
16163
16299
  try {
16164
- void Promise.resolve(
16165
- client.retain(
16166
- `\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.)`,
16167
- "hindsight codebase-survey baseline",
16168
- `${SURVEY_BASELINE_PREFIX}${sha}`,
16169
- [SURVEY_BASELINE_TAG],
16170
- "survey"
16171
- )
16172
- ).catch(() => {
16300
+ const stamp = retainStamp();
16301
+ 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.)`;
16302
+ const tags = [.../* @__PURE__ */ new Set([...stamp.tags, SURVEY_BASELINE_TAG])];
16303
+ const retained = client.retain(
16304
+ content,
16305
+ "hindsight codebase-survey baseline",
16306
+ `${SURVEY_BASELINE_PREFIX}${sha}`,
16307
+ tags,
16308
+ "survey",
16309
+ // `retain` only sets metadata when it is truthy, so an empty stamp sends none.
16310
+ { metadata: Object.keys(stamp.metadata).length ? stamp.metadata : void 0 }
16311
+ );
16312
+ void Promise.resolve(retained).catch(() => {
16173
16313
  });
16174
16314
  } catch {
16175
16315
  }
@@ -16261,7 +16401,7 @@ async function buildSessionStartContext(args) {
16261
16401
  }
16262
16402
 
16263
16403
  // src/core/hook.ts
16264
- import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
16404
+ import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
16265
16405
 
16266
16406
  // src/core/inject.ts
16267
16407
  function buildReflectQuery(prompt) {
@@ -16308,7 +16448,10 @@ async function buildHookOutput(args) {
16308
16448
  const t0 = Date.now();
16309
16449
  try {
16310
16450
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
16311
- budget: "high",
16451
+ // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
16452
+ // supported default for bounded reflect calls; callers that explicitly invoke the MCP
16453
+ // tool still get the deeper high-budget path.
16454
+ budget: "low",
16312
16455
  timeoutMs: Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS)
16313
16456
  });
16314
16457
  diag(harness, reflectAnswer ? "reflect_ok" : "reflect_empty", {
@@ -16417,7 +16560,15 @@ var RuntimeCore = class {
16417
16560
  }
16418
16561
  /** The hindsight_* knowledge + recall tools, bound to this bank, for the harness to register natively. */
16419
16562
  toolSpecs() {
16420
- return buildKnowledgeTools(this.client, this.bankId, { harness: this.harness });
16563
+ return buildKnowledgeTools(this.client, this.bankId, {
16564
+ repoDir: this.projectDir,
16565
+ harness: this.harness,
16566
+ stampFor: () => buildRetainStamp(this.cfg, {
16567
+ directory: this.projectDir,
16568
+ harness: this.harness,
16569
+ bankId: this.bankId
16570
+ })
16571
+ });
16421
16572
  }
16422
16573
  get writeBackEnabled() {
16423
16574
  return this.cfg.retainSessions;
@@ -16494,19 +16645,22 @@ var RuntimeCore = class {
16494
16645
  return keyed ?? this.lastInjection ?? void 0;
16495
16646
  }
16496
16647
  /**
16497
- * Full normalized transcript (rich: user/assistant text + tool calls/outputs): upsert every N user
16498
- * turns when enabled. On by default for persistent-plugin hosts (parity with hook-harness Stop write-back),
16499
- * so opencode sessions compound into memory; a user can opt out with `retainSessions: false`.
16648
+ * Full normalized transcript (rich: user/assistant text + tool calls/outputs): upsert every turn
16649
+ * when enabled. On by default for persistent-plugin hosts (parity with hook-harness Stop
16650
+ * write-back), so opencode sessions compound into memory; opt out with `retainSessions: false`.
16651
+ *
16652
+ * There is deliberately no client-side cadence. Batching write-backs meant holding turns in a
16653
+ * process the host can close at any moment, with no reliable signal on the way out — the flush a
16654
+ * cadence needs would have to ride a session-end hook, and those are cancelled at shutdown. The
16655
+ * server coalesces instead: queued retains for one document fold into a single execution
16656
+ * (`engine.retain.fold`), so submitting every turn costs one extraction, not one per turn, and
16657
+ * nothing is ever held somewhere it can be lost.
16500
16658
  */
16501
16659
  async onTranscript(sessionId2, turns) {
16502
16660
  if (process.env.HINDSIGHT_DISABLE_HOOKS) return;
16503
16661
  if (!this.writeBackEnabled || !sessionId2 || !turns.length) return;
16504
- const users = turns.filter((t) => t.role === "user").length;
16505
16662
  const st = this.stateFor(sessionId2);
16506
- if (users - st.retainedUsers >= this.cfg.retainEveryTurns) {
16507
- st.retainedUsers = users;
16508
- this.retain(sessionId2, turns, st.startTs);
16509
- }
16663
+ this.retain(sessionId2, turns, st.startTs);
16510
16664
  }
16511
16665
  /**
16512
16666
  * Session went idle — the assistant has finished replying.
@@ -16537,13 +16691,12 @@ var RuntimeCore = class {
16537
16691
  const st = this.stateFor(sessionId2);
16538
16692
  if (turns.length <= st.retainedTurns) return;
16539
16693
  st.retainedTurns = turns.length;
16540
- st.retainedUsers = turns.filter((t) => t.role === "user").length;
16541
16694
  this.retain(sessionId2, turns, st.startTs, "idle");
16542
16695
  }
16543
16696
  stateFor(sessionId2) {
16544
16697
  let st = this.sessionState.get(sessionId2);
16545
16698
  if (!st) {
16546
- st = { startTs: (/* @__PURE__ */ new Date()).toISOString(), retainedUsers: 0, retainedTurns: 0 };
16699
+ st = { startTs: (/* @__PURE__ */ new Date()).toISOString(), retainedTurns: 0 };
16547
16700
  this.sessionState.set(sessionId2, st);
16548
16701
  }
16549
16702
  return st;
@@ -16680,7 +16833,8 @@ function createRuntime(workspaceRoot) {
16680
16833
  const client = new HindsightClient({
16681
16834
  apiUrl: cfg.apiUrl,
16682
16835
  apiToken: cfg.apiToken,
16683
- bank: resolved.bankId
16836
+ bank: resolved.bankId,
16837
+ maxParallelRetains: cfg.maxParallelRetains
16684
16838
  });
16685
16839
  return new RuntimeCore(client, resolved.bankId, cfg, HARNESS2, workspaceRoot || process.cwd());
16686
16840
  }