@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/cline.js CHANGED
@@ -6,8 +6,8 @@ var __export = (target, all) => {
6
6
 
7
7
  // src/core/config.ts
8
8
  import { readFileSync } from "fs";
9
- import { homedir } from "os";
10
- import { join as join2 } from "path";
9
+ import { homedir as homedir2 } from "os";
10
+ import { join as join3 } from "path";
11
11
 
12
12
  // src/core/seed.ts
13
13
  import { spawn as realSpawn } from "child_process";
@@ -41,8 +41,117 @@ function startBackgroundSeed(repoDir, opts = {}) {
41
41
  }
42
42
  }
43
43
 
44
+ // src/core/bank.ts
45
+ import { execFileSync } from "child_process";
46
+ import { existsSync } from "fs";
47
+ import { homedir } from "os";
48
+ import { basename, dirname as dirname2, join as join2, normalize, sep } from "path";
49
+
50
+ // src/core/template.ts
51
+ var PLACEHOLDER = /\{([a-zA-Z_]+)\}/g;
52
+ function applyTemplate(template, resolvers, what) {
53
+ return template.replace(PLACEHOLDER, (_, name) => {
54
+ const resolve2 = resolvers[name];
55
+ if (!resolve2) {
56
+ console.error(
57
+ `hindsight: unknown ${what} placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
58
+ );
59
+ return "unknown";
60
+ }
61
+ return resolve2();
62
+ });
63
+ }
64
+
65
+ // src/core/bank.ts
66
+ var DEFAULT_BANK_NAME = "coding";
67
+ var DEFAULT_TEMPLATE = "coding-agent::{gitProject}";
68
+ function getProjectRootFromGit(directory) {
69
+ if (!directory) return null;
70
+ try {
71
+ const commonDir = execFileSync(
72
+ "git",
73
+ ["rev-parse", "--path-format=absolute", "--git-common-dir"],
74
+ { cwd: directory, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1e3 }
75
+ ).trim();
76
+ if (!commonDir) return null;
77
+ return basename(commonDir) === ".git" ? dirname2(commonDir) : commonDir;
78
+ } catch {
79
+ return null;
80
+ }
81
+ }
82
+ function projectNameOf(directory) {
83
+ return gitProjectName(directory, true);
84
+ }
85
+ var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
86
+ function nearestExistingDir(directory) {
87
+ let current2 = directory;
88
+ while (current2) {
89
+ if (existsSync(current2)) return current2;
90
+ const parent = dirname2(current2);
91
+ if (parent === current2) return "";
92
+ current2 = parent;
93
+ }
94
+ return "";
95
+ }
96
+ function dirName(directory) {
97
+ return directory && basename(directory) || "unknown";
98
+ }
99
+ function gitProjectName(directory, resolveWorktrees) {
100
+ if (resolveWorktrees) {
101
+ const candidates = [
102
+ nearestExistingDir(directory),
103
+ ...PROJECT_ROOT_ENV.map((v) => process.env[v] || "")
104
+ ];
105
+ for (const candidate of candidates) {
106
+ const root = candidate ? getProjectRootFromGit(candidate) : null;
107
+ if (root) return basename(root);
108
+ }
109
+ }
110
+ return dirName(directory);
111
+ }
112
+ function configuredDir(dir) {
113
+ const expanded = dir === "~" || dir.startsWith("~/") ? join2(homedir(), dir.slice(1)) : dir;
114
+ return normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
115
+ }
116
+ function isWithin(directory, configured) {
117
+ return directory === configured || directory.startsWith(configured + sep);
118
+ }
119
+ function mapLookup(map2, directory) {
120
+ const cwd = normalize(directory);
121
+ let best;
122
+ for (const [dir, bank] of Object.entries(map2)) {
123
+ const p = configuredDir(dir);
124
+ if (isWithin(cwd, p)) {
125
+ if (!best || p.length > best.len) best = { len: p.length, bank };
126
+ }
127
+ }
128
+ return best?.bank;
129
+ }
130
+ function isOptedIn(config2, directory) {
131
+ if (!config2.optInOnly) return true;
132
+ if (!directory) return false;
133
+ const cwd = normalize(directory);
134
+ if ((config2.optInPaths ?? []).some((dir) => dir && isWithin(cwd, configuredDir(dir))))
135
+ return true;
136
+ return Boolean(config2.mapPathToBank && mapLookup(config2.mapPathToBank, directory));
137
+ }
138
+ function deriveBankId(config2, directory, harness = "coding") {
139
+ const mapped = directory && config2.mapPathToBank ? mapLookup(config2.mapPathToBank, directory) : void 0;
140
+ if (mapped) return mapped;
141
+ const dynamic = config2.dynamicBankId ?? !config2.bankId;
142
+ if (!dynamic) return config2.bankId || DEFAULT_BANK_NAME;
143
+ const resolvers = {
144
+ harness: () => harness,
145
+ project: () => dirName(directory),
146
+ gitProject: () => gitProjectName(directory, config2.resolveWorktrees ?? true),
147
+ channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
148
+ user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
149
+ };
150
+ return applyTemplate(config2.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
151
+ }
152
+
44
153
  // src/core/config.ts
45
- var CONFIG_PATH = process.env.HINDSIGHT_CONFIG || join2(homedir(), ".hindsight", "coding-agent.json");
154
+ var CONFIG_PATH = process.env.HINDSIGHT_CONFIG || join3(homedir2(), ".hindsight", "coding-agent.json");
46
155
  var DEFAULT_DAEMON_PORT = 9077;
47
156
  var DEFAULT_DAEMON_IDLE_TIMEOUT = 300;
48
157
  var DEFAULT_DAEMON_PROFILE = "coding-agent";
@@ -66,11 +175,14 @@ function resolveConfig(raw = {}) {
66
175
  bankIdTemplate: raw.bankIdTemplate,
67
176
  mapPathToBank: raw.mapPathToBank,
68
177
  resolveWorktrees: raw.resolveWorktrees,
178
+ optInOnly: raw.optInOnly ?? false,
179
+ // Same shape as retainTags: a config typo must not become a path that silently approves nothing.
180
+ optInPaths: Array.isArray(raw.optInPaths) ? raw.optInPaths.filter((p) => typeof p === "string" && p.trim() !== "") : [],
69
181
  harness: raw.harness ?? "opencode",
70
182
  disabled: raw.disabled ?? false,
71
183
  retainSessions: raw.retainSessions ?? true,
72
184
  // opencode: write back by default (parity with hook-harness Stop)
73
- retainEveryTurns: raw.retainEveryTurns || 1,
185
+ maxParallelRetains: raw.maxParallelRetains || 10,
74
186
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
75
187
  autoReflect: raw.autoReflect ?? true,
76
188
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
@@ -126,10 +238,12 @@ var ENV_KEYS = {
126
238
  dynamicBankId: "HINDSIGHT_DYNAMIC_BANK_ID",
127
239
  bankIdTemplate: "HINDSIGHT_BANK_ID_TEMPLATE",
128
240
  resolveWorktrees: "HINDSIGHT_RESOLVE_WORKTREES",
241
+ optInOnly: "HINDSIGHT_OPT_IN_ONLY",
242
+ optInPaths: "HINDSIGHT_OPT_IN_PATHS",
129
243
  harness: "HINDSIGHT_HARNESS",
130
244
  disabled: "HINDSIGHT_DISABLED",
131
245
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
132
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
246
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
133
247
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
134
248
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
135
249
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
@@ -148,17 +262,18 @@ var ENV_KEYS = {
148
262
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
149
263
  "dynamicBankId",
150
264
  "resolveWorktrees",
265
+ "optInOnly",
151
266
  "disabled",
152
267
  "retainSessions",
153
268
  "autoReflect",
154
269
  "autoSeed",
155
270
  "codebaseSurvey"
156
271
  ]);
157
- var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
272
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags", "optInPaths"]);
158
273
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
159
274
  "apiPort",
160
275
  "daemonIdleTimeout",
161
- "retainEveryTurns",
276
+ "maxParallelRetains",
162
277
  "reflectTimeoutMs",
163
278
  "pageRefreshEveryTurns",
164
279
  "seedLimit",
@@ -198,9 +313,15 @@ var BANK_OVERRIDE_EXCLUDED = [
198
313
  "mapPathToBank",
199
314
  "dynamicBankId",
200
315
  "resolveWorktrees",
316
+ // Approval is decided BEFORE the bank is resolved, so a `banks.<id>` section naming these could
317
+ // only ever arrive too late to matter — strip them rather than let them read as effective.
318
+ "optInOnly",
319
+ "optInPaths",
201
320
  "harness"
202
321
  ];
203
- function applyBankConfig(cfg, resolvedId) {
322
+ function applyBankConfig(cfg, resolvedId, directory) {
323
+ if (directory !== void 0 && !isOptedIn(cfg, directory))
324
+ return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
204
325
  const section = cfg.banks[resolvedId];
205
326
  if (!section) return { cfg, bankId: resolvedId };
206
327
  const safe = { ...section };
@@ -220,80 +341,6 @@ function resolvePartial(cfg, patch) {
220
341
  return out;
221
342
  }
222
343
 
223
- // src/core/bank.ts
224
- import { execFileSync } from "child_process";
225
- import { homedir as homedir2 } from "os";
226
- import { basename, dirname as dirname2, join as join3, normalize, sep } from "path";
227
-
228
- // src/core/template.ts
229
- var PLACEHOLDER = /\{([a-zA-Z_]+)\}/g;
230
- function applyTemplate(template, resolvers, what) {
231
- return template.replace(PLACEHOLDER, (_, name) => {
232
- const resolve2 = resolvers[name];
233
- if (!resolve2) {
234
- console.error(
235
- `hindsight: unknown ${what} placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
236
- );
237
- return "unknown";
238
- }
239
- return resolve2();
240
- });
241
- }
242
-
243
- // src/core/bank.ts
244
- var DEFAULT_BANK_NAME = "coding";
245
- var DEFAULT_TEMPLATE = "coding-agent::{gitProject}";
246
- function getProjectRootFromGit(directory) {
247
- if (!directory) return null;
248
- try {
249
- const commonDir = execFileSync(
250
- "git",
251
- ["rev-parse", "--path-format=absolute", "--git-common-dir"],
252
- { cwd: directory, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1e3 }
253
- ).trim();
254
- if (!commonDir) return null;
255
- return basename(commonDir) === ".git" ? dirname2(commonDir) : commonDir;
256
- } catch {
257
- return null;
258
- }
259
- }
260
- function projectNameOf(directory) {
261
- return gitProjectName(directory, true);
262
- }
263
- function gitProjectName(directory, resolveWorktrees) {
264
- if (resolveWorktrees) {
265
- const root = getProjectRootFromGit(directory);
266
- if (root) return basename(root);
267
- }
268
- return directory ? basename(directory) : "unknown";
269
- }
270
- function mapLookup(map2, directory) {
271
- const cwd = normalize(directory);
272
- let best;
273
- for (const [dir, bank] of Object.entries(map2)) {
274
- const expanded = dir === "~" || dir.startsWith("~/") ? join3(homedir2(), dir.slice(1)) : dir;
275
- const p = normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
276
- if (cwd === p || cwd.startsWith(p + sep)) {
277
- if (!best || p.length > best.len) best = { len: p.length, bank };
278
- }
279
- }
280
- return best?.bank;
281
- }
282
- function deriveBankId(config2, directory, harness = "coding") {
283
- const mapped = directory && config2.mapPathToBank ? mapLookup(config2.mapPathToBank, directory) : void 0;
284
- if (mapped) return mapped;
285
- const dynamic = config2.dynamicBankId ?? !config2.bankId;
286
- if (!dynamic) return config2.bankId || DEFAULT_BANK_NAME;
287
- const resolvers = {
288
- harness: () => harness,
289
- project: () => directory ? basename(directory) : "unknown",
290
- gitProject: () => gitProjectName(directory, config2.resolveWorktrees ?? true),
291
- channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
292
- user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
293
- };
294
- return applyTemplate(config2.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
295
- }
296
-
297
344
  // src/core/missions.ts
298
345
  var GIT_MISSION = "You are ingesting a single git commit: its message and its full diff. Extract the concrete technical DECISION and the CAUSE/INVARIANT it encodes, bound to the specific code entities (functions, methods, files) and behaviors it changes. Preserve exact identifiers, paths, and literal values verbatim. Preserve the 'REF-ID: <token>' marker verbatim in every fact. Capture both WHAT changed and WHY. Issue/PR references (#123, GH-123, PROJ-123) are load-bearing: keep them VERBATIM in the fact text and emit each as an ENTITY, so a later question about that issue or PR retrieves this decision.";
299
346
  var GITLOG_MISSION = "You are ingesting an aggregated block of git commit MESSAGES ONLY (no diffs) \u2014 the project's recent commit-message history, newest first. Extract the project's INITIATIVES, FEATURES, ENHANCEMENTS, and notable changes or THEMES over time \u2014 what the project has been working on and how it has evolved. Do NOT extract per-line code detail (there is no diff to draw it from). Group related commits into a coherent initiative/theme where the messages make that clear; preserve exact identifiers and literal values verbatim when quoting a subject line. Keep issue/PR references (#123, GH-123) VERBATIM and emit each as an ENTITY \u2014 they are how future sessions will ask about this work.";
@@ -438,9 +485,40 @@ function semverGte(version2, min) {
438
485
  }
439
486
  return true;
440
487
  }
488
+ async function pool(items, n, fn, onError, onProgress) {
489
+ let i = 0, done = 0;
490
+ async function worker() {
491
+ while (i < items.length) {
492
+ const idx = i++;
493
+ try {
494
+ await fn(items[idx], idx);
495
+ } catch (e) {
496
+ onError?.(idx, e);
497
+ }
498
+ onProgress?.(++done, items.length);
499
+ }
500
+ }
501
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
502
+ }
441
503
 
442
504
  // src/core/hindsight.ts
443
505
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
506
+ var RateLimitedError = class extends Error {
507
+ constructor(retryAfterMs2) {
508
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
509
+ this.retryAfterMs = retryAfterMs2;
510
+ this.name = "RateLimitedError";
511
+ }
512
+ retryAfterMs;
513
+ code = "rate_limited";
514
+ };
515
+ function retryAfterMs(header) {
516
+ if (!header) return 0;
517
+ const secs = Number(header.trim());
518
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
519
+ const at = Date.parse(header);
520
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
521
+ }
444
522
  var KnowledgePagesUnavailableError = class extends Error {
445
523
  code = "knowledge_pages_unavailable";
446
524
  constructor() {
@@ -449,6 +527,10 @@ var KnowledgePagesUnavailableError = class extends Error {
449
527
  }
450
528
  };
451
529
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
530
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
531
+ var POLL_CYCLE_MS = 5e3;
532
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
533
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
452
534
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
453
535
  var HindsightClient = class {
454
536
  apiUrl;
@@ -461,12 +543,14 @@ var HindsightClient = class {
461
543
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
462
544
  idempotentRetain;
463
545
  log;
546
+ maxParallelRetains;
464
547
  constructor(o) {
465
548
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
466
549
  this.apiToken = o.apiToken;
467
550
  this.bank = o.bank;
468
551
  this.log = o.log ?? (() => {
469
552
  });
553
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
470
554
  }
471
555
  headers() {
472
556
  const h = { "Content-Type": "application/json" };
@@ -484,6 +568,8 @@ var HindsightClient = class {
484
568
  body: body ? JSON.stringify(body) : void 0,
485
569
  signal: AbortSignal.timeout(15e3)
486
570
  });
571
+ if (r.status === 429 && !tolerate.includes(429))
572
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
487
573
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
488
574
  throw new Error(`${method} ${url2} -> ${r.status} ${await r.text()}`);
489
575
  return r;
@@ -615,7 +701,14 @@ var HindsightClient = class {
615
701
  return 0;
616
702
  }
617
703
  }
618
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
704
+ /**
705
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
706
+ *
707
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
708
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
709
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
710
+ * of hammering the next cycle 5s later.
711
+ */
619
712
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
620
713
  if (!ids.length) return;
621
714
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -623,23 +716,29 @@ var HindsightClient = class {
623
716
  const pending = new Set(ids);
624
717
  let failed = 0;
625
718
  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 {
719
+ let backoffMs = POLL_CYCLE_MS;
720
+ await pool([...pending], this.maxParallelRetains, async (id) => {
721
+ try {
722
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
723
+ if (r.status === 429) {
724
+ backoffMs = Math.min(
725
+ RETRY_AFTER_CEILING_MS,
726
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
727
+ );
728
+ return;
637
729
  }
638
- })
639
- );
730
+ if (!r.ok) return;
731
+ const st = ((await r.json()).status || "").toLowerCase();
732
+ if (TERMINAL.has(st)) {
733
+ pending.delete(id);
734
+ if (st !== "completed") failed++;
735
+ }
736
+ } catch {
737
+ }
738
+ });
640
739
  if (pending.size) {
641
740
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
642
- await sleep(5e3);
741
+ await sleep(backoffMs);
643
742
  }
644
743
  }
645
744
  this.log(
@@ -839,13 +938,20 @@ var HindsightClient = class {
839
938
  const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
840
939
  const content = `${verb}: ${args.title}. ${args.summary}`;
841
940
  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
- );
941
+ const tags = [
942
+ .../* @__PURE__ */ new Set([
943
+ ...args.stamp?.tags ?? [],
944
+ "knowledge:feature-work",
945
+ `relatedPageId:${pageId}`
946
+ ])
947
+ ];
948
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
949
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
950
+ metadata: args.stamp?.metadata
951
+ });
952
+ } else {
953
+ await this.retain(content, "initiative marker", markerId, tags, "document");
954
+ }
849
955
  return { page_id: pageId };
850
956
  }
851
957
  /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
@@ -15430,7 +15536,7 @@ function date4(params) {
15430
15536
  config(en_default());
15431
15537
 
15432
15538
  // src/core/knowledge-tools.ts
15433
- import { existsSync as existsSync2 } from "fs";
15539
+ import { existsSync as existsSync3 } from "fs";
15434
15540
  import { homedir as homedir4 } from "os";
15435
15541
  import { join as join6 } from "path";
15436
15542
 
@@ -15515,7 +15621,7 @@ ${toolGuide(opts)}
15515
15621
 
15516
15622
  // src/core/survey.ts
15517
15623
  import { spawn as realSpawn2 } from "child_process";
15518
- import { accessSync, constants, existsSync } from "fs";
15624
+ import { accessSync, constants, existsSync as existsSync2 } from "fs";
15519
15625
  import { homedir as homedir3 } from "os";
15520
15626
  import { delimiter, dirname as dirname4, join as join5 } from "path";
15521
15627
  import { fileURLToPath as fileURLToPath2 } from "url";
@@ -15530,7 +15636,7 @@ function resolveClaudeBin(explicit) {
15530
15636
  if (process.env.HINDSIGHT_CLAUDE_BIN) return process.env.HINDSIGHT_CLAUDE_BIN;
15531
15637
  const nativeInstallPath = join5(homedir3(), ".claude", "local", "claude");
15532
15638
  try {
15533
- if (existsSync(nativeInstallPath)) return nativeInstallPath;
15639
+ if (existsSync2(nativeInstallPath)) return nativeInstallPath;
15534
15640
  } catch {
15535
15641
  }
15536
15642
  return "claude";
@@ -15804,7 +15910,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15804
15910
  workspace: opts.repoDir ?? process.cwd(),
15805
15911
  config: {
15806
15912
  path: configPath,
15807
- exists: existsSync2(configPath),
15913
+ exists: existsSync3(configPath),
15808
15914
  api_url: cfg.apiUrl,
15809
15915
  api_token_configured: Boolean(cfg.apiToken),
15810
15916
  disabled: cfg.disabled
@@ -15869,7 +15975,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15869
15975
  relates_to_page_id: external_exports.string().optional()
15870
15976
  },
15871
15977
  handler: guarded(
15872
- async ({ title, summary, relates_to_page_id }) => client.captureInitiative({ title, summary, relatesToPageId: relates_to_page_id })
15978
+ async ({ title, summary, relates_to_page_id }) => client.captureInitiative({
15979
+ title,
15980
+ summary,
15981
+ relatesToPageId: relates_to_page_id,
15982
+ ...opts.stampFor ? { stamp: opts.stampFor() } : {}
15983
+ })
15873
15984
  )
15874
15985
  },
15875
15986
  {
@@ -15878,13 +15989,24 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15878
15989
  inputSchema: { title: external_exports.string(), content: external_exports.string() },
15879
15990
  handler: guarded(async ({ title, content }) => {
15880
15991
  const docId = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "doc";
15992
+ const stamp = opts.stampFor?.();
15993
+ const metadata = {
15994
+ ...stamp?.metadata,
15995
+ ...opts.harness ? { harness: opts.harness } : {}
15996
+ };
15881
15997
  await client.retain(
15882
15998
  content,
15883
15999
  "ingested document",
15884
16000
  docId,
15885
- ["source:upload", ...opts.harness ? [`harness:${opts.harness}`] : []],
16001
+ [
16002
+ .../* @__PURE__ */ new Set([
16003
+ ...stamp?.tags ?? [],
16004
+ "source:upload",
16005
+ ...opts.harness ? [`harness:${opts.harness}`] : []
16006
+ ])
16007
+ ],
15886
16008
  "document",
15887
- { metadata: opts.harness ? { harness: opts.harness } : void 0 }
16009
+ Object.keys(metadata).length ? { metadata } : {}
15888
16010
  );
15889
16011
  return { ok: true, doc_id: docId };
15890
16012
  })
@@ -15951,6 +16073,23 @@ async function supportsAppend(client) {
15951
16073
  return false;
15952
16074
  }
15953
16075
  }
16076
+ var RETAIN_RETRY_ATTEMPTS = 2;
16077
+ var RETAIN_RETRY_BUDGET_MS = 6e3;
16078
+ async function submitWithRetry(send, isStillNewest) {
16079
+ let spent = 0;
16080
+ for (let attempt = 0; ; attempt++) {
16081
+ try {
16082
+ return await send();
16083
+ } catch (e) {
16084
+ const limited = e instanceof RateLimitedError;
16085
+ if (!limited || attempt >= RETAIN_RETRY_ATTEMPTS || !isStillNewest()) throw e;
16086
+ const wait = e.retryAfterMs || 1e3;
16087
+ if (wait > RETAIN_RETRY_BUDGET_MS - spent) throw e;
16088
+ spent += wait;
16089
+ await sleep(wait);
16090
+ }
16091
+ }
16092
+ }
15954
16093
  var writeBacks = /* @__PURE__ */ new WeakMap();
15955
16094
  function serialize(cursors, sessionId2, write2) {
15956
16095
  const perSession = writeBacks.get(cursors) ?? /* @__PURE__ */ new Map();
@@ -15985,37 +16124,46 @@ async function writeSession(client, sessionId2, turns, startTs, harness, stamp,
15985
16124
  bank: client.bank
15986
16125
  };
15987
16126
  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}
16127
+ const claimed = { ...next, dirty: true };
16128
+ await submitWithRetry(
16129
+ () => client.retain(
16130
+ content,
16131
+ "coding agent session",
16132
+ refId,
16133
+ // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
16134
+ // the documents list filters and draws its agent logo from, so a template cannot displace them.
16135
+ [
16136
+ .../* @__PURE__ */ new Set([
16137
+ ...stamp?.tags ?? [],
16138
+ "source:chat",
16139
+ ...harness ? [`harness:${harness}`] : []
16140
+ ])
16141
+ ],
16142
+ "conversation",
16143
+ {
16144
+ timestamp: startTs,
16145
+ updateMode: plan.mode === "append" ? "append" : void 0,
16146
+ // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
16147
+ // the original operation instead of extracting (or appending) twice.
16148
+ operationId: uuidV5(`${client.bank}
16008
16149
  ${refId}
16009
16150
  ${plan.mode}
16010
16151
  ${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 } : {}
16152
+ metadata: {
16153
+ ...stamp?.metadata,
16154
+ // configured first: the built-ins below win on any key collision
16155
+ source: "chat",
16156
+ session_id: sessionId2,
16157
+ ref_id: refId,
16158
+ ...harness ? { harness } : {}
16159
+ }
16018
16160
  }
16161
+ ),
16162
+ // Still ours to retry only while the cursor holds the claim we wrote above.
16163
+ () => {
16164
+ if (!cursors) return true;
16165
+ const now = cursors.read(sessionId2);
16166
+ return now?.turns === claimed.turns && now?.fingerprint === claimed.fingerprint;
16019
16167
  }
16020
16168
  );
16021
16169
  cursors?.write(sessionId2, next);
@@ -16032,7 +16180,7 @@ function resolversFor(ctx) {
16032
16180
  project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
16033
16181
  harness: () => ctx.harness,
16034
16182
  bankId: () => ctx.bankId,
16035
- sessionId: () => ctx.sessionId,
16183
+ sessionId: () => ctx.sessionId ?? "unknown",
16036
16184
  timestamp: () => (/* @__PURE__ */ new Date()).toISOString(),
16037
16185
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
16038
16186
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -16072,7 +16220,7 @@ function buildRetainStamp(cfg, ctx) {
16072
16220
  import { readFileSync as readFileSync4 } from "fs";
16073
16221
 
16074
16222
  // src/core/skill-sync.ts
16075
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
16223
+ import { cpSync, existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
16076
16224
  import { homedir as homedir5 } from "os";
16077
16225
  import { dirname as dirname5, join as join7 } from "path";
16078
16226
  import { fileURLToPath as fileURLToPath3 } from "url";
@@ -16097,7 +16245,7 @@ function brandWord() {
16097
16245
  }
16098
16246
 
16099
16247
  // src/core/session-cache.ts
16100
- import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync } from "fs";
16248
+ import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync, rmSync, writeFileSync } from "fs";
16101
16249
  import { tmpdir as tmpdir2 } from "os";
16102
16250
  import { dirname as dirname7, join as join9 } from "path";
16103
16251
  function sessionCacheFile(harness, sessionId2) {
@@ -16110,10 +16258,23 @@ function readSessionCache(cacheFile) {
16110
16258
  return {};
16111
16259
  }
16112
16260
  }
16261
+ function writeFileAtomic(path, body) {
16262
+ mkdirSync2(dirname7(path), { recursive: true });
16263
+ const tmp = `${path}.${process.pid}.tmp`;
16264
+ try {
16265
+ writeFileSync(tmp, body);
16266
+ renameSync(tmp, path);
16267
+ } catch (e) {
16268
+ try {
16269
+ rmSync(tmp, { force: true });
16270
+ } catch {
16271
+ }
16272
+ throw e;
16273
+ }
16274
+ }
16113
16275
  function writeSessionCache(cacheFile, cache) {
16114
16276
  try {
16115
- mkdirSync2(dirname7(cacheFile), { recursive: true });
16116
- writeFileSync(cacheFile, JSON.stringify(cache));
16277
+ writeFileAtomic(cacheFile, JSON.stringify(cache));
16117
16278
  } catch {
16118
16279
  }
16119
16280
  }
@@ -16156,20 +16317,25 @@ async function buildSessionStartContext(args) {
16156
16317
  const startSurvey = args.startSurvey ?? startCodebaseSurvey;
16157
16318
  const resolveHeadSha = args.headSha ?? gitHeadSha;
16158
16319
  const countCommitsSince = args.commitsSince ?? commitsSince;
16320
+ const retainStamp = () => buildRetainStamp(cfg, { directory: cwd, harness, bankId });
16159
16321
  const SURVEY_BASELINE_TAG = "source:survey-baseline";
16160
16322
  const SURVEY_BASELINE_PREFIX = "survey-baseline:";
16161
16323
  const recordSurveyBaseline = (sha) => {
16162
16324
  if (!client.retain) return;
16163
16325
  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(() => {
16326
+ const stamp = retainStamp();
16327
+ 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.)`;
16328
+ const tags = [.../* @__PURE__ */ new Set([...stamp.tags, SURVEY_BASELINE_TAG])];
16329
+ const retained = client.retain(
16330
+ content,
16331
+ "hindsight codebase-survey baseline",
16332
+ `${SURVEY_BASELINE_PREFIX}${sha}`,
16333
+ tags,
16334
+ "survey",
16335
+ // `retain` only sets metadata when it is truthy, so an empty stamp sends none.
16336
+ { metadata: Object.keys(stamp.metadata).length ? stamp.metadata : void 0 }
16337
+ );
16338
+ void Promise.resolve(retained).catch(() => {
16173
16339
  });
16174
16340
  } catch {
16175
16341
  }
@@ -16261,7 +16427,7 @@ async function buildSessionStartContext(args) {
16261
16427
  }
16262
16428
 
16263
16429
  // src/core/hook.ts
16264
- import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
16430
+ import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
16265
16431
 
16266
16432
  // src/core/inject.ts
16267
16433
  function buildReflectQuery(prompt) {
@@ -16308,7 +16474,10 @@ async function buildHookOutput(args) {
16308
16474
  const t0 = Date.now();
16309
16475
  try {
16310
16476
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
16311
- budget: "high",
16477
+ // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
16478
+ // supported default for bounded reflect calls; callers that explicitly invoke the MCP
16479
+ // tool still get the deeper high-budget path.
16480
+ budget: "low",
16312
16481
  timeoutMs: Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS)
16313
16482
  });
16314
16483
  diag(harness, reflectAnswer ? "reflect_ok" : "reflect_empty", {
@@ -16417,7 +16586,15 @@ var RuntimeCore = class {
16417
16586
  }
16418
16587
  /** The hindsight_* knowledge + recall tools, bound to this bank, for the harness to register natively. */
16419
16588
  toolSpecs() {
16420
- return buildKnowledgeTools(this.client, this.bankId, { harness: this.harness });
16589
+ return buildKnowledgeTools(this.client, this.bankId, {
16590
+ repoDir: this.projectDir,
16591
+ harness: this.harness,
16592
+ stampFor: () => buildRetainStamp(this.cfg, {
16593
+ directory: this.projectDir,
16594
+ harness: this.harness,
16595
+ bankId: this.bankId
16596
+ })
16597
+ });
16421
16598
  }
16422
16599
  get writeBackEnabled() {
16423
16600
  return this.cfg.retainSessions;
@@ -16494,19 +16671,22 @@ var RuntimeCore = class {
16494
16671
  return keyed ?? this.lastInjection ?? void 0;
16495
16672
  }
16496
16673
  /**
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`.
16674
+ * Full normalized transcript (rich: user/assistant text + tool calls/outputs): upsert every turn
16675
+ * when enabled. On by default for persistent-plugin hosts (parity with hook-harness Stop
16676
+ * write-back), so opencode sessions compound into memory; opt out with `retainSessions: false`.
16677
+ *
16678
+ * There is deliberately no client-side cadence. Batching write-backs meant holding turns in a
16679
+ * process the host can close at any moment, with no reliable signal on the way out — the flush a
16680
+ * cadence needs would have to ride a session-end hook, and those are cancelled at shutdown. The
16681
+ * server coalesces instead: queued retains for one document fold into a single execution
16682
+ * (`engine.retain.fold`), so submitting every turn costs one extraction, not one per turn, and
16683
+ * nothing is ever held somewhere it can be lost.
16500
16684
  */
16501
16685
  async onTranscript(sessionId2, turns) {
16502
16686
  if (process.env.HINDSIGHT_DISABLE_HOOKS) return;
16503
16687
  if (!this.writeBackEnabled || !sessionId2 || !turns.length) return;
16504
- const users = turns.filter((t) => t.role === "user").length;
16505
16688
  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
- }
16689
+ this.retain(sessionId2, turns, st.startTs);
16510
16690
  }
16511
16691
  /**
16512
16692
  * Session went idle — the assistant has finished replying.
@@ -16537,13 +16717,12 @@ var RuntimeCore = class {
16537
16717
  const st = this.stateFor(sessionId2);
16538
16718
  if (turns.length <= st.retainedTurns) return;
16539
16719
  st.retainedTurns = turns.length;
16540
- st.retainedUsers = turns.filter((t) => t.role === "user").length;
16541
16720
  this.retain(sessionId2, turns, st.startTs, "idle");
16542
16721
  }
16543
16722
  stateFor(sessionId2) {
16544
16723
  let st = this.sessionState.get(sessionId2);
16545
16724
  if (!st) {
16546
- st = { startTs: (/* @__PURE__ */ new Date()).toISOString(), retainedUsers: 0, retainedTurns: 0 };
16725
+ st = { startTs: (/* @__PURE__ */ new Date()).toISOString(), retainedTurns: 0 };
16547
16726
  this.sessionState.set(sessionId2, st);
16548
16727
  }
16549
16728
  return st;
@@ -16674,13 +16853,18 @@ function createClineHooks(core, configuredSessionId, sessionStart) {
16674
16853
  function createRuntime(workspaceRoot) {
16675
16854
  let cfg = loadConfig({ harness: HARNESS2 });
16676
16855
  if (cfg.disabled) return void 0;
16677
- const resolved = applyBankConfig(cfg, deriveBankId(cfg, workspaceRoot || process.cwd(), HARNESS2));
16856
+ const resolved = applyBankConfig(
16857
+ cfg,
16858
+ deriveBankId(cfg, workspaceRoot || process.cwd(), HARNESS2),
16859
+ workspaceRoot || process.cwd()
16860
+ );
16678
16861
  cfg = resolved.cfg;
16679
16862
  if (cfg.disabled) return void 0;
16680
16863
  const client = new HindsightClient({
16681
16864
  apiUrl: cfg.apiUrl,
16682
16865
  apiToken: cfg.apiToken,
16683
- bank: resolved.bankId
16866
+ bank: resolved.bankId,
16867
+ maxParallelRetains: cfg.maxParallelRetains
16684
16868
  });
16685
16869
  return new RuntimeCore(client, resolved.bankId, cfg, HARNESS2, workspaceRoot || process.cwd());
16686
16870
  }