@vectorize-io/hindsight-coding-agents 0.2.0 → 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/index.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,12 +48,32 @@ 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);
56
77
  }
57
78
  function mapLookup(map3, directory) {
58
79
  const cwd = normalize(directory);
@@ -73,7 +94,7 @@ function deriveBankId(config3, directory, harness = "coding") {
73
94
  if (!dynamic) return config3.bankId || DEFAULT_BANK_NAME;
74
95
  const resolvers = {
75
96
  harness: () => harness,
76
- project: () => directory ? basename(directory) : "unknown",
97
+ project: () => dirName(directory),
77
98
  gitProject: () => gitProjectName(directory, config3.resolveWorktrees ?? true),
78
99
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
79
100
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -147,7 +168,7 @@ function resolveConfig(raw = {}) {
147
168
  disabled: raw.disabled ?? false,
148
169
  retainSessions: raw.retainSessions ?? true,
149
170
  // opencode: write back by default (parity with hook-harness Stop)
150
- retainEveryTurns: raw.retainEveryTurns || 1,
171
+ maxParallelRetains: raw.maxParallelRetains || 10,
151
172
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
152
173
  autoReflect: raw.autoReflect ?? true,
153
174
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
@@ -206,7 +227,7 @@ var ENV_KEYS = {
206
227
  harness: "HINDSIGHT_HARNESS",
207
228
  disabled: "HINDSIGHT_DISABLED",
208
229
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
209
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
230
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
210
231
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
211
232
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
212
233
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
@@ -235,7 +256,7 @@ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
235
256
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
236
257
  "apiPort",
237
258
  "daemonIdleTimeout",
238
- "retainEveryTurns",
259
+ "maxParallelRetains",
239
260
  "reflectTimeoutMs",
240
261
  "pageRefreshEveryTurns",
241
262
  "seedLimit",
@@ -474,9 +495,40 @@ function semverGte(version3, min) {
474
495
  }
475
496
  return true;
476
497
  }
498
+ async function pool(items, n, fn, onError, onProgress) {
499
+ let i = 0, done = 0;
500
+ async function worker() {
501
+ while (i < items.length) {
502
+ const idx = i++;
503
+ try {
504
+ await fn(items[idx], idx);
505
+ } catch (e) {
506
+ onError?.(idx, e);
507
+ }
508
+ onProgress?.(++done, items.length);
509
+ }
510
+ }
511
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
512
+ }
477
513
 
478
514
  // src/core/hindsight.ts
479
515
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
516
+ var RateLimitedError = class extends Error {
517
+ constructor(retryAfterMs2) {
518
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
519
+ this.retryAfterMs = retryAfterMs2;
520
+ this.name = "RateLimitedError";
521
+ }
522
+ retryAfterMs;
523
+ code = "rate_limited";
524
+ };
525
+ function retryAfterMs(header) {
526
+ if (!header) return 0;
527
+ const secs = Number(header.trim());
528
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
529
+ const at = Date.parse(header);
530
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
531
+ }
480
532
  var KnowledgePagesUnavailableError = class extends Error {
481
533
  code = "knowledge_pages_unavailable";
482
534
  constructor() {
@@ -485,6 +537,10 @@ var KnowledgePagesUnavailableError = class extends Error {
485
537
  }
486
538
  };
487
539
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
540
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
541
+ var POLL_CYCLE_MS = 5e3;
542
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
543
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
488
544
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
489
545
  var HindsightClient = class {
490
546
  apiUrl;
@@ -497,12 +553,14 @@ var HindsightClient = class {
497
553
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
498
554
  idempotentRetain;
499
555
  log;
556
+ maxParallelRetains;
500
557
  constructor(o) {
501
558
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
502
559
  this.apiToken = o.apiToken;
503
560
  this.bank = o.bank;
504
561
  this.log = o.log ?? (() => {
505
562
  });
563
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
506
564
  }
507
565
  headers() {
508
566
  const h = { "Content-Type": "application/json" };
@@ -520,6 +578,8 @@ var HindsightClient = class {
520
578
  body: body ? JSON.stringify(body) : void 0,
521
579
  signal: AbortSignal.timeout(15e3)
522
580
  });
581
+ if (r.status === 429 && !tolerate.includes(429))
582
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
523
583
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
524
584
  throw new Error(`${method} ${url3} -> ${r.status} ${await r.text()}`);
525
585
  return r;
@@ -651,7 +711,14 @@ var HindsightClient = class {
651
711
  return 0;
652
712
  }
653
713
  }
654
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
714
+ /**
715
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
716
+ *
717
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
718
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
719
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
720
+ * of hammering the next cycle 5s later.
721
+ */
655
722
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
656
723
  if (!ids.length) return;
657
724
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -659,23 +726,29 @@ var HindsightClient = class {
659
726
  const pending = new Set(ids);
660
727
  let failed = 0;
661
728
  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 {
729
+ let backoffMs = POLL_CYCLE_MS;
730
+ await pool([...pending], this.maxParallelRetains, async (id) => {
731
+ try {
732
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
733
+ if (r.status === 429) {
734
+ backoffMs = Math.min(
735
+ RETRY_AFTER_CEILING_MS,
736
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
737
+ );
738
+ return;
673
739
  }
674
- })
675
- );
740
+ if (!r.ok) return;
741
+ const st = ((await r.json()).status || "").toLowerCase();
742
+ if (TERMINAL.has(st)) {
743
+ pending.delete(id);
744
+ if (st !== "completed") failed++;
745
+ }
746
+ } catch {
747
+ }
748
+ });
676
749
  if (pending.size) {
677
750
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
678
- await sleep(5e3);
751
+ await sleep(backoffMs);
679
752
  }
680
753
  }
681
754
  this.log(
@@ -875,13 +948,20 @@ var HindsightClient = class {
875
948
  const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
876
949
  const content = `${verb}: ${args.title}. ${args.summary}`;
877
950
  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
- );
951
+ const tags = [
952
+ .../* @__PURE__ */ new Set([
953
+ ...args.stamp?.tags ?? [],
954
+ "knowledge:feature-work",
955
+ `relatedPageId:${pageId}`
956
+ ])
957
+ ];
958
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
959
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
960
+ metadata: args.stamp?.metadata
961
+ });
962
+ } else {
963
+ await this.retain(content, "initiative marker", markerId, tags, "document");
964
+ }
885
965
  return { page_id: pageId };
886
966
  }
887
967
  /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
@@ -15431,7 +15511,7 @@ function date4(params) {
15431
15511
  config(en_default());
15432
15512
 
15433
15513
  // src/core/knowledge-tools.ts
15434
- import { existsSync as existsSync2 } from "fs";
15514
+ import { existsSync as existsSync3 } from "fs";
15435
15515
  import { homedir as homedir4 } from "os";
15436
15516
  import { join as join6 } from "path";
15437
15517
 
@@ -15516,7 +15596,7 @@ ${toolGuide(opts)}
15516
15596
 
15517
15597
  // src/core/survey.ts
15518
15598
  import { spawn as realSpawn2 } from "child_process";
15519
- import { accessSync, constants, existsSync } from "fs";
15599
+ import { accessSync, constants, existsSync as existsSync2 } from "fs";
15520
15600
  import { homedir as homedir3 } from "os";
15521
15601
  import { delimiter, dirname as dirname4, join as join5 } from "path";
15522
15602
  import { fileURLToPath as fileURLToPath2 } from "url";
@@ -15531,7 +15611,7 @@ function resolveClaudeBin(explicit) {
15531
15611
  if (process.env.HINDSIGHT_CLAUDE_BIN) return process.env.HINDSIGHT_CLAUDE_BIN;
15532
15612
  const nativeInstallPath = join5(homedir3(), ".claude", "local", "claude");
15533
15613
  try {
15534
- if (existsSync(nativeInstallPath)) return nativeInstallPath;
15614
+ if (existsSync2(nativeInstallPath)) return nativeInstallPath;
15535
15615
  } catch {
15536
15616
  }
15537
15617
  return "claude";
@@ -15805,7 +15885,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15805
15885
  workspace: opts.repoDir ?? process.cwd(),
15806
15886
  config: {
15807
15887
  path: configPath,
15808
- exists: existsSync2(configPath),
15888
+ exists: existsSync3(configPath),
15809
15889
  api_url: cfg.apiUrl,
15810
15890
  api_token_configured: Boolean(cfg.apiToken),
15811
15891
  disabled: cfg.disabled
@@ -15870,7 +15950,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15870
15950
  relates_to_page_id: external_exports.string().optional()
15871
15951
  },
15872
15952
  handler: guarded(
15873
- async ({ title, summary, relates_to_page_id }) => client.captureInitiative({ title, summary, relatesToPageId: relates_to_page_id })
15953
+ async ({ title, summary, relates_to_page_id }) => client.captureInitiative({
15954
+ title,
15955
+ summary,
15956
+ relatesToPageId: relates_to_page_id,
15957
+ ...opts.stampFor ? { stamp: opts.stampFor() } : {}
15958
+ })
15874
15959
  )
15875
15960
  },
15876
15961
  {
@@ -15879,13 +15964,24 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15879
15964
  inputSchema: { title: external_exports.string(), content: external_exports.string() },
15880
15965
  handler: guarded(async ({ title, content }) => {
15881
15966
  const docId = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "doc";
15967
+ const stamp = opts.stampFor?.();
15968
+ const metadata = {
15969
+ ...stamp?.metadata,
15970
+ ...opts.harness ? { harness: opts.harness } : {}
15971
+ };
15882
15972
  await client.retain(
15883
15973
  content,
15884
15974
  "ingested document",
15885
15975
  docId,
15886
- ["source:upload", ...opts.harness ? [`harness:${opts.harness}`] : []],
15976
+ [
15977
+ .../* @__PURE__ */ new Set([
15978
+ ...stamp?.tags ?? [],
15979
+ "source:upload",
15980
+ ...opts.harness ? [`harness:${opts.harness}`] : []
15981
+ ])
15982
+ ],
15887
15983
  "document",
15888
- { metadata: opts.harness ? { harness: opts.harness } : void 0 }
15984
+ Object.keys(metadata).length ? { metadata } : {}
15889
15985
  );
15890
15986
  return { ok: true, doc_id: docId };
15891
15987
  })
@@ -15952,6 +16048,23 @@ async function supportsAppend(client) {
15952
16048
  return false;
15953
16049
  }
15954
16050
  }
16051
+ var RETAIN_RETRY_ATTEMPTS = 2;
16052
+ var RETAIN_RETRY_BUDGET_MS = 6e3;
16053
+ async function submitWithRetry(send, isStillNewest) {
16054
+ let spent = 0;
16055
+ for (let attempt = 0; ; attempt++) {
16056
+ try {
16057
+ return await send();
16058
+ } catch (e) {
16059
+ const limited = e instanceof RateLimitedError;
16060
+ if (!limited || attempt >= RETAIN_RETRY_ATTEMPTS || !isStillNewest()) throw e;
16061
+ const wait = e.retryAfterMs || 1e3;
16062
+ if (wait > RETAIN_RETRY_BUDGET_MS - spent) throw e;
16063
+ spent += wait;
16064
+ await sleep(wait);
16065
+ }
16066
+ }
16067
+ }
15955
16068
  var writeBacks = /* @__PURE__ */ new WeakMap();
15956
16069
  function serialize(cursors, sessionId, write2) {
15957
16070
  const perSession = writeBacks.get(cursors) ?? /* @__PURE__ */ new Map();
@@ -15986,37 +16099,46 @@ async function writeSession(client, sessionId, turns, startTs, harness, stamp, c
15986
16099
  bank: client.bank
15987
16100
  };
15988
16101
  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}
16102
+ const claimed = { ...next, dirty: true };
16103
+ await submitWithRetry(
16104
+ () => client.retain(
16105
+ content,
16106
+ "coding agent session",
16107
+ refId,
16108
+ // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
16109
+ // the documents list filters and draws its agent logo from, so a template cannot displace them.
16110
+ [
16111
+ .../* @__PURE__ */ new Set([
16112
+ ...stamp?.tags ?? [],
16113
+ "source:chat",
16114
+ ...harness ? [`harness:${harness}`] : []
16115
+ ])
16116
+ ],
16117
+ "conversation",
16118
+ {
16119
+ timestamp: startTs,
16120
+ updateMode: plan.mode === "append" ? "append" : void 0,
16121
+ // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
16122
+ // the original operation instead of extracting (or appending) twice.
16123
+ operationId: uuidV5(`${client.bank}
16009
16124
  ${refId}
16010
16125
  ${plan.mode}
16011
16126
  ${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
- }
16127
+ metadata: {
16128
+ ...stamp?.metadata,
16129
+ // configured first: the built-ins below win on any key collision
16130
+ source: "chat",
16131
+ session_id: sessionId,
16132
+ ref_id: refId,
16133
+ ...harness ? { harness } : {}
16134
+ }
16135
+ }
16136
+ ),
16137
+ // Still ours to retry only while the cursor holds the claim we wrote above.
16138
+ () => {
16139
+ if (!cursors) return true;
16140
+ const now = cursors.read(sessionId);
16141
+ return now?.turns === claimed.turns && now?.fingerprint === claimed.fingerprint;
16020
16142
  }
16021
16143
  );
16022
16144
  cursors?.write(sessionId, next);
@@ -16033,7 +16155,7 @@ function resolversFor(ctx) {
16033
16155
  project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
16034
16156
  harness: () => ctx.harness,
16035
16157
  bankId: () => ctx.bankId,
16036
- sessionId: () => ctx.sessionId,
16158
+ sessionId: () => ctx.sessionId ?? "unknown",
16037
16159
  timestamp: () => (/* @__PURE__ */ new Date()).toISOString(),
16038
16160
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
16039
16161
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -16073,7 +16195,7 @@ function buildRetainStamp(cfg, ctx) {
16073
16195
  import { readFileSync as readFileSync4 } from "fs";
16074
16196
 
16075
16197
  // src/core/skill-sync.ts
16076
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
16198
+ import { cpSync, existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
16077
16199
  import { homedir as homedir5 } from "os";
16078
16200
  import { dirname as dirname5, join as join7 } from "path";
16079
16201
  import { fileURLToPath as fileURLToPath3 } from "url";
@@ -16098,7 +16220,7 @@ function brandWord() {
16098
16220
  }
16099
16221
 
16100
16222
  // src/core/session-cache.ts
16101
- import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync } from "fs";
16223
+ import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync, rmSync, writeFileSync } from "fs";
16102
16224
  import { tmpdir as tmpdir2 } from "os";
16103
16225
  import { dirname as dirname7, join as join9 } from "path";
16104
16226
  function sessionCacheFile(harness, sessionId) {
@@ -16111,10 +16233,23 @@ function readSessionCache(cacheFile) {
16111
16233
  return {};
16112
16234
  }
16113
16235
  }
16236
+ function writeFileAtomic(path, body) {
16237
+ mkdirSync2(dirname7(path), { recursive: true });
16238
+ const tmp = `${path}.${process.pid}.tmp`;
16239
+ try {
16240
+ writeFileSync(tmp, body);
16241
+ renameSync(tmp, path);
16242
+ } catch (e) {
16243
+ try {
16244
+ rmSync(tmp, { force: true });
16245
+ } catch {
16246
+ }
16247
+ throw e;
16248
+ }
16249
+ }
16114
16250
  function writeSessionCache(cacheFile, cache) {
16115
16251
  try {
16116
- mkdirSync2(dirname7(cacheFile), { recursive: true });
16117
- writeFileSync(cacheFile, JSON.stringify(cache));
16252
+ writeFileAtomic(cacheFile, JSON.stringify(cache));
16118
16253
  } catch {
16119
16254
  }
16120
16255
  }
@@ -16157,20 +16292,25 @@ async function buildSessionStartContext(args) {
16157
16292
  const startSurvey = args.startSurvey ?? startCodebaseSurvey;
16158
16293
  const resolveHeadSha = args.headSha ?? gitHeadSha;
16159
16294
  const countCommitsSince = args.commitsSince ?? commitsSince;
16295
+ const retainStamp = () => buildRetainStamp(cfg, { directory: cwd, harness, bankId });
16160
16296
  const SURVEY_BASELINE_TAG = "source:survey-baseline";
16161
16297
  const SURVEY_BASELINE_PREFIX = "survey-baseline:";
16162
16298
  const recordSurveyBaseline = (sha) => {
16163
16299
  if (!client.retain) return;
16164
16300
  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(() => {
16301
+ const stamp = retainStamp();
16302
+ 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.)`;
16303
+ const tags = [.../* @__PURE__ */ new Set([...stamp.tags, SURVEY_BASELINE_TAG])];
16304
+ const retained = client.retain(
16305
+ content,
16306
+ "hindsight codebase-survey baseline",
16307
+ `${SURVEY_BASELINE_PREFIX}${sha}`,
16308
+ tags,
16309
+ "survey",
16310
+ // `retain` only sets metadata when it is truthy, so an empty stamp sends none.
16311
+ { metadata: Object.keys(stamp.metadata).length ? stamp.metadata : void 0 }
16312
+ );
16313
+ void Promise.resolve(retained).catch(() => {
16174
16314
  });
16175
16315
  } catch {
16176
16316
  }
@@ -16262,7 +16402,7 @@ async function buildSessionStartContext(args) {
16262
16402
  }
16263
16403
 
16264
16404
  // src/core/hook.ts
16265
- import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
16405
+ import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
16266
16406
 
16267
16407
  // src/core/inject.ts
16268
16408
  function buildReflectQuery(prompt) {
@@ -16309,7 +16449,10 @@ async function buildHookOutput(args) {
16309
16449
  const t0 = Date.now();
16310
16450
  try {
16311
16451
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
16312
- budget: "high",
16452
+ // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
16453
+ // supported default for bounded reflect calls; callers that explicitly invoke the MCP
16454
+ // tool still get the deeper high-budget path.
16455
+ budget: "low",
16313
16456
  timeoutMs: Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS)
16314
16457
  });
16315
16458
  diag(harness, reflectAnswer ? "reflect_ok" : "reflect_empty", {
@@ -16418,7 +16561,15 @@ var RuntimeCore = class {
16418
16561
  }
16419
16562
  /** The hindsight_* knowledge + recall tools, bound to this bank, for the harness to register natively. */
16420
16563
  toolSpecs() {
16421
- return buildKnowledgeTools(this.client, this.bankId, { harness: this.harness });
16564
+ return buildKnowledgeTools(this.client, this.bankId, {
16565
+ repoDir: this.projectDir,
16566
+ harness: this.harness,
16567
+ stampFor: () => buildRetainStamp(this.cfg, {
16568
+ directory: this.projectDir,
16569
+ harness: this.harness,
16570
+ bankId: this.bankId
16571
+ })
16572
+ });
16422
16573
  }
16423
16574
  get writeBackEnabled() {
16424
16575
  return this.cfg.retainSessions;
@@ -16495,19 +16646,22 @@ var RuntimeCore = class {
16495
16646
  return keyed ?? this.lastInjection ?? void 0;
16496
16647
  }
16497
16648
  /**
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`.
16649
+ * Full normalized transcript (rich: user/assistant text + tool calls/outputs): upsert every turn
16650
+ * when enabled. On by default for persistent-plugin hosts (parity with hook-harness Stop
16651
+ * write-back), so opencode sessions compound into memory; opt out with `retainSessions: false`.
16652
+ *
16653
+ * There is deliberately no client-side cadence. Batching write-backs meant holding turns in a
16654
+ * process the host can close at any moment, with no reliable signal on the way out — the flush a
16655
+ * cadence needs would have to ride a session-end hook, and those are cancelled at shutdown. The
16656
+ * server coalesces instead: queued retains for one document fold into a single execution
16657
+ * (`engine.retain.fold`), so submitting every turn costs one extraction, not one per turn, and
16658
+ * nothing is ever held somewhere it can be lost.
16501
16659
  */
16502
16660
  async onTranscript(sessionId, turns) {
16503
16661
  if (process.env.HINDSIGHT_DISABLE_HOOKS) return;
16504
16662
  if (!this.writeBackEnabled || !sessionId || !turns.length) return;
16505
- const users = turns.filter((t) => t.role === "user").length;
16506
16663
  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
- }
16664
+ this.retain(sessionId, turns, st.startTs);
16511
16665
  }
16512
16666
  /**
16513
16667
  * Session went idle — the assistant has finished replying.
@@ -16538,13 +16692,12 @@ var RuntimeCore = class {
16538
16692
  const st = this.stateFor(sessionId);
16539
16693
  if (turns.length <= st.retainedTurns) return;
16540
16694
  st.retainedTurns = turns.length;
16541
- st.retainedUsers = turns.filter((t) => t.role === "user").length;
16542
16695
  this.retain(sessionId, turns, st.startTs, "idle");
16543
16696
  }
16544
16697
  stateFor(sessionId) {
16545
16698
  let st = this.sessionState.get(sessionId);
16546
16699
  if (!st) {
16547
- st = { startTs: (/* @__PURE__ */ new Date()).toISOString(), retainedUsers: 0, retainedTurns: 0 };
16700
+ st = { startTs: (/* @__PURE__ */ new Date()).toISOString(), retainedTurns: 0 };
16548
16701
  this.sessionState.set(sessionId, st);
16549
16702
  }
16550
16703
  return st;
@@ -29160,7 +29313,8 @@ function createPluginEntry(harness) {
29160
29313
  const client = new HindsightClient({
29161
29314
  apiUrl: cfg.apiUrl,
29162
29315
  apiToken: cfg.apiToken,
29163
- bank: bankId
29316
+ bank: bankId,
29317
+ maxParallelRetains: cfg.maxParallelRetains
29164
29318
  });
29165
29319
  const core = new RuntimeCore(client, bankId, cfg, harness, projectDir || process.cwd());
29166
29320
  const oc = input?.client;