@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/deepen.js CHANGED
@@ -8,6 +8,7 @@ import { join as join6 } from "path";
8
8
 
9
9
  // src/core/bank.ts
10
10
  import { execFileSync } from "child_process";
11
+ import { existsSync } from "fs";
11
12
  import { homedir } from "os";
12
13
  import { basename, dirname, join, normalize, sep } from "path";
13
14
 
@@ -46,25 +47,59 @@ function getProjectRootFromGit(directory) {
46
47
  function projectNameOf(directory) {
47
48
  return gitProjectName(directory, true);
48
49
  }
50
+ var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
51
+ function nearestExistingDir(directory) {
52
+ let current2 = directory;
53
+ while (current2) {
54
+ if (existsSync(current2)) return current2;
55
+ const parent = dirname(current2);
56
+ if (parent === current2) return "";
57
+ current2 = parent;
58
+ }
59
+ return "";
60
+ }
61
+ function dirName(directory) {
62
+ return directory && basename(directory) || "unknown";
63
+ }
49
64
  function gitProjectName(directory, resolveWorktrees) {
50
65
  if (resolveWorktrees) {
51
- const root = getProjectRootFromGit(directory);
52
- if (root) return basename(root);
66
+ const candidates = [
67
+ nearestExistingDir(directory),
68
+ ...PROJECT_ROOT_ENV.map((v) => process.env[v] || "")
69
+ ];
70
+ for (const candidate of candidates) {
71
+ const root = candidate ? getProjectRootFromGit(candidate) : null;
72
+ if (root) return basename(root);
73
+ }
53
74
  }
54
- return directory ? basename(directory) : "unknown";
75
+ return dirName(directory);
76
+ }
77
+ function configuredDir(dir) {
78
+ const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
79
+ return normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
80
+ }
81
+ function isWithin(directory, configured) {
82
+ return directory === configured || directory.startsWith(configured + sep);
55
83
  }
56
84
  function mapLookup(map, directory) {
57
85
  const cwd = normalize(directory);
58
86
  let best;
59
87
  for (const [dir, bank] of Object.entries(map)) {
60
- const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
61
- const p = normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
62
- if (cwd === p || cwd.startsWith(p + sep)) {
88
+ const p = configuredDir(dir);
89
+ if (isWithin(cwd, p)) {
63
90
  if (!best || p.length > best.len) best = { len: p.length, bank };
64
91
  }
65
92
  }
66
93
  return best?.bank;
67
94
  }
95
+ function isOptedIn(config, directory) {
96
+ if (!config.optInOnly) return true;
97
+ if (!directory) return false;
98
+ const cwd = normalize(directory);
99
+ if ((config.optInPaths ?? []).some((dir) => dir && isWithin(cwd, configuredDir(dir))))
100
+ return true;
101
+ return Boolean(config.mapPathToBank && mapLookup(config.mapPathToBank, directory));
102
+ }
68
103
  function deriveBankId(config, directory, harness = "coding") {
69
104
  const mapped = directory && config.mapPathToBank ? mapLookup(config.mapPathToBank, directory) : void 0;
70
105
  if (mapped) return mapped;
@@ -72,7 +107,7 @@ function deriveBankId(config, directory, harness = "coding") {
72
107
  if (!dynamic) return config.bankId || DEFAULT_BANK_NAME;
73
108
  const resolvers = {
74
109
  harness: () => harness,
75
- project: () => directory ? basename(directory) : "unknown",
110
+ project: () => dirName(directory),
76
111
  gitProject: () => gitProjectName(directory, config.resolveWorktrees ?? true),
77
112
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
78
113
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -80,408 +115,6 @@ function deriveBankId(config, directory, harness = "coding") {
80
115
  return applyTemplate(config.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
81
116
  }
82
117
 
83
- // src/core/retain-cursor.ts
84
- import { createHash } from "crypto";
85
-
86
- // src/core/uuid.ts
87
- import { createHash as createHash2 } from "crypto";
88
-
89
- // src/core/util.ts
90
- var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
91
- function semverGte(version, min) {
92
- const parts = (v) => {
93
- const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
94
- return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
95
- };
96
- const a = version ? parts(version) : void 0;
97
- const b = parts(min);
98
- if (!a || !b) return false;
99
- for (let i = 0; i < 3; i++) {
100
- if (a[i] !== b[i]) return a[i] > b[i];
101
- }
102
- return true;
103
- }
104
- async function pool(items, n, fn, onError, onProgress) {
105
- let i = 0, done = 0;
106
- async function worker() {
107
- while (i < items.length) {
108
- const idx = i++;
109
- try {
110
- await fn(items[idx], idx);
111
- } catch (e) {
112
- onError?.(idx, e);
113
- }
114
- onProgress?.(++done, items.length);
115
- }
116
- }
117
- await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
118
- }
119
-
120
- // src/core/chat.ts
121
- function withRefId(refId, turns, baseTs) {
122
- return [{ role: "system", content: `REF-ID: ${refId}`, timestamp: baseTs }, ...turns];
123
- }
124
- async function ingestChats(client, sessions, opts = {}) {
125
- const log3 = opts.log ?? (() => {
126
- });
127
- if (!sessions.length) {
128
- log3("[chat] no sessions; skipping");
129
- return 0;
130
- }
131
- log3(`[chat] ingesting ${sessions.length} chats (RAW, JSONL transcript \u2014 one turn per line) \u2026`);
132
- const NOW = Date.now();
133
- let failures = 0;
134
- await pool(
135
- sessions,
136
- opts.concurrency ?? 8,
137
- async (s, i) => {
138
- const id = s.id || `s${i}`;
139
- const sessBase = NOW - (sessions.length - 1 - i) * 36e5;
140
- const baseIso = new Date(sessBase).toISOString();
141
- const turns = withRefId(
142
- `chat:${id}`,
143
- (s.turns || []).map((t, j) => ({
144
- role: t.role,
145
- content: t.text,
146
- timestamp: t.timestamp || new Date(sessBase + (j + 1) * 6e4).toISOString()
147
- })),
148
- baseIso
149
- );
150
- await client.retain(
151
- turns.map((x) => JSON.stringify(x)).join("\n"),
152
- "developer chat",
153
- `chat:${id}`,
154
- ["source:chat"],
155
- "conversation",
156
- {
157
- timestamp: baseIso,
158
- metadata: { source: "chat", chat: id, ref_id: `chat:${id}` }
159
- }
160
- );
161
- },
162
- (i, e) => {
163
- failures++;
164
- log3(` ! chat ${i} failed to enqueue: ${e.message?.slice(0, 120)}`);
165
- }
166
- );
167
- log3(`[chat] done: ${sessions.length} chats ingested (JSONL) under strategy 'chat'`);
168
- return failures;
169
- }
170
-
171
- // src/core/config.ts
172
- import { readFileSync } from "fs";
173
- import { homedir as homedir2 } from "os";
174
- import { join as join3 } from "path";
175
-
176
- // src/core/seed.ts
177
- import { spawn as realSpawn } from "child_process";
178
- import { dirname as dirname2, join as join2 } from "path";
179
- import { fileURLToPath } from "url";
180
- var DEFAULT_SEED_LIMIT = 300;
181
-
182
- // src/core/config.ts
183
- var CONFIG_PATH = process.env.HINDSIGHT_CONFIG || join3(homedir2(), ".hindsight", "coding-agent.json");
184
- var DEFAULT_DAEMON_PORT = 9077;
185
- var DEFAULT_DAEMON_IDLE_TIMEOUT = 300;
186
- var DEFAULT_DAEMON_PROFILE = "coding-agent";
187
- function resolveConfig(raw = {}) {
188
- const serverMode = ["cloud", "self-hosted", "daemon"].includes(raw.serverMode) ? raw.serverMode : "cloud";
189
- const apiPort = raw.apiPort || DEFAULT_DAEMON_PORT;
190
- return {
191
- serverMode,
192
- // Daemon mode resolves the URL HERE rather than at each call site: every entry point already
193
- // builds its client from cfg.apiUrl, so collapsing the mode into that one field means the
194
- // daemon needs no plumbing through eight separate constructors.
195
- apiUrl: serverMode === "daemon" ? `http://127.0.0.1:${apiPort}` : raw.apiUrl ?? "https://api.hindsight.vectorize.io",
196
- apiToken: raw.apiToken || void 0,
197
- apiPort,
198
- daemonIdleTimeout: raw.daemonIdleTimeout ?? DEFAULT_DAEMON_IDLE_TIMEOUT,
199
- daemonProfile: raw.daemonProfile || DEFAULT_DAEMON_PROFILE,
200
- embedVersion: raw.embedVersion || void 0,
201
- embedPackagePath: raw.embedPackagePath || void 0,
202
- bankId: raw.bankId,
203
- dynamicBankId: raw.dynamicBankId,
204
- bankIdTemplate: raw.bankIdTemplate,
205
- mapPathToBank: raw.mapPathToBank,
206
- resolveWorktrees: raw.resolveWorktrees,
207
- harness: raw.harness ?? "opencode",
208
- disabled: raw.disabled ?? false,
209
- retainSessions: raw.retainSessions ?? true,
210
- // opencode: write back by default (parity with hook-harness Stop)
211
- retainEveryTurns: raw.retainEveryTurns || 1,
212
- reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
213
- autoReflect: raw.autoReflect ?? true,
214
- pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
215
- autoSeed: raw.autoSeed ?? true,
216
- seedLimit: raw.seedLimit || DEFAULT_SEED_LIMIT,
217
- codebaseSurvey: raw.codebaseSurvey ?? true,
218
- surveyModel: raw.surveyModel || "haiku",
219
- surveyBudgetUsd: raw.surveyBudgetUsd || 2,
220
- surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
221
- gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
222
- // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
223
- // nested object cannot reach the API as a tag and fail the whole retain.
224
- retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
225
- retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
226
- Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
227
- ) : {},
228
- banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
229
- logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
230
- };
231
- }
232
- function readRaw(path) {
233
- try {
234
- return JSON.parse(readFileSync(path, "utf8"));
235
- } catch (e) {
236
- if (e?.code !== "ENOENT") {
237
- console.error(`hindsight: ignoring invalid config at ${path}: ${e?.message || e}`);
238
- }
239
- return {};
240
- }
241
- }
242
- function mergeRaw(a, b) {
243
- const { harnesses: _drop, ...flat } = b;
244
- return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
245
- }
246
- function applyLayer(raw, layer, harness) {
247
- let out = mergeRaw(raw, layer);
248
- const perHarness = harness ? layer.harnesses?.[harness] : void 0;
249
- if (perHarness) out = mergeRaw(out, perHarness);
250
- return out;
251
- }
252
- var ENV_KEYS = {
253
- serverMode: "HINDSIGHT_SERVER_MODE",
254
- apiUrl: "HINDSIGHT_API_URL",
255
- apiToken: "HINDSIGHT_API_TOKEN",
256
- // These four keep the names the old per-agent Claude Code plugin used, so a user migrating from
257
- // it can carry their existing environment over unchanged.
258
- apiPort: "HINDSIGHT_API_PORT",
259
- daemonIdleTimeout: "HINDSIGHT_DAEMON_IDLE_TIMEOUT",
260
- embedVersion: "HINDSIGHT_EMBED_VERSION",
261
- embedPackagePath: "HINDSIGHT_EMBED_PACKAGE_PATH",
262
- daemonProfile: "HINDSIGHT_DAEMON_PROFILE",
263
- bankId: "HINDSIGHT_BANK_ID",
264
- dynamicBankId: "HINDSIGHT_DYNAMIC_BANK_ID",
265
- bankIdTemplate: "HINDSIGHT_BANK_ID_TEMPLATE",
266
- resolveWorktrees: "HINDSIGHT_RESOLVE_WORKTREES",
267
- harness: "HINDSIGHT_HARNESS",
268
- disabled: "HINDSIGHT_DISABLED",
269
- retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
270
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
271
- reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
272
- autoReflect: "HINDSIGHT_AUTO_REFLECT",
273
- pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
274
- autoSeed: "HINDSIGHT_AUTO_SEED",
275
- seedLimit: "HINDSIGHT_SEED_LIMIT",
276
- codebaseSurvey: "HINDSIGHT_CODEBASE_SURVEY",
277
- surveyModel: "HINDSIGHT_SURVEY_MODEL",
278
- surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
279
- surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
280
- logLevel: "HINDSIGHT_LOG_LEVEL",
281
- gitIngest: "HINDSIGHT_GIT_INGEST",
282
- // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
283
- // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
284
- retainTags: "HINDSIGHT_RETAIN_TAGS"
285
- };
286
- var ENV_BOOLEANS = /* @__PURE__ */ new Set([
287
- "dynamicBankId",
288
- "resolveWorktrees",
289
- "disabled",
290
- "retainSessions",
291
- "autoReflect",
292
- "autoSeed",
293
- "codebaseSurvey"
294
- ]);
295
- var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
296
- var ENV_NUMBERS = /* @__PURE__ */ new Set([
297
- "apiPort",
298
- "daemonIdleTimeout",
299
- "retainEveryTurns",
300
- "reflectTimeoutMs",
301
- "pageRefreshEveryTurns",
302
- "seedLimit",
303
- "surveyBudgetUsd",
304
- "surveyRefreshCommits"
305
- ]);
306
- function readEnvConfig(env = process.env) {
307
- const out = {};
308
- for (const [key, name] of Object.entries(ENV_KEYS)) {
309
- const value = env[name];
310
- if (value === void 0 || value.trim() === "") continue;
311
- if (ENV_BOOLEANS.has(key)) {
312
- out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
313
- } else if (ENV_LISTS.has(key)) {
314
- const items = value.split(",").map((v) => v.trim()).filter(Boolean);
315
- if (items.length) out[key] = items;
316
- } else if (ENV_NUMBERS.has(key)) {
317
- const n = Number(value);
318
- if (Number.isFinite(n)) out[key] = n;
319
- else console.error(`hindsight: ignoring ${name}=${value} \u2014 not a number`);
320
- } else {
321
- out[key] = value;
322
- }
323
- }
324
- return out;
325
- }
326
- function loadConfig(opts = {}) {
327
- const o = typeof opts === "string" ? { path: opts } : opts;
328
- const withEnv = applyLayer({}, readEnvConfig(), o.harness);
329
- const raw = applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness);
330
- if (!raw.harness && o.harness) raw.harness = o.harness;
331
- return resolveConfig(raw);
332
- }
333
- var BANK_OVERRIDE_EXCLUDED = [
334
- "bankId",
335
- "bankIdTemplate",
336
- "mapPathToBank",
337
- "dynamicBankId",
338
- "resolveWorktrees",
339
- "harness"
340
- ];
341
- function applyBankConfig(cfg2, resolvedId) {
342
- const section = cfg2.banks[resolvedId];
343
- if (!section) return { cfg: cfg2, bankId: resolvedId };
344
- const safe = { ...section };
345
- for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
346
- delete safe.banks;
347
- const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
348
- delete safe.bank;
349
- return { cfg: { ...cfg2, ...resolvePartial(cfg2, safe) }, bankId };
350
- }
351
- function resolvePartial(cfg2, patch) {
352
- const full = resolveConfig(patch);
353
- const out = {};
354
- for (const key of Object.keys(patch)) {
355
- if (key in full)
356
- out[key] = full[key];
357
- }
358
- return out;
359
- }
360
-
361
- // src/core/git.ts
362
- import { execFileSync as execFileSync2 } from "child_process";
363
- import { resolve } from "path";
364
- var US = "";
365
- var RS = "";
366
- function git(repo, ...args) {
367
- return execFileSync2("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
368
- }
369
- function repoNameOf(repo) {
370
- return projectNameOf(resolve(repo));
371
- }
372
- function gitHeadSha(dir) {
373
- try {
374
- return git(dir, "rev-parse", "HEAD").trim() || null;
375
- } catch {
376
- return null;
377
- }
378
- }
379
- function commitsSince(dir, sinceSha) {
380
- try {
381
- const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
382
- return Number.isFinite(n) ? n : null;
383
- } catch {
384
- return null;
385
- }
386
- }
387
- async function retainCommit(client, repo, sha, repoName) {
388
- const [h, an, ae, aISO, cISO, subj, body] = git(
389
- repo,
390
- "show",
391
- "-s",
392
- `--format=%H${US}%an${US}%ae${US}%aI${US}%cI${US}%s${US}%b`,
393
- sha
394
- ).split(US);
395
- const msg = (subj + (body?.trim() ? "\n\n" + body.trim() : "")).trim();
396
- const diff = git(repo, "show", "--format=", sha);
397
- const content = `REF-ID: git:${sha.slice(0, 12)}
398
- Git commit ${sha.slice(0, 12)} in the ${repoName} repository (${an}, ${aISO}).
399
-
400
- Message:
401
- ${msg}
402
-
403
- Diff:
404
- ${diff}`;
405
- await client.retain(content, `git commit in ${repoName}`, `git:${sha}`, ["source:git"], "git", {
406
- timestamp: aISO,
407
- // the memory's timestamp is the commit's author date
408
- metadata: {
409
- source: "git",
410
- repo: repoName,
411
- commit: h,
412
- short_sha: sha.slice(0, 12),
413
- author: an,
414
- author_email: ae,
415
- authored_at: aISO,
416
- committed_at: cISO,
417
- subject: subj
418
- }
419
- });
420
- }
421
- function gitLogText(repo, limit) {
422
- let raw;
423
- try {
424
- raw = git(
425
- repo,
426
- "log",
427
- `-n`,
428
- String(limit),
429
- "--no-merges",
430
- "--date=short",
431
- `--format=%h${US}%ad${US}%an${US}%s${US}%b${RS}`
432
- );
433
- } catch {
434
- return "";
435
- }
436
- return raw.split(RS).map((rec) => rec.trim()).filter(Boolean).map((rec) => {
437
- const [sha, date, author, subj, body] = rec.split(US);
438
- const header = `${sha} ${date} ${author}`;
439
- const msg = subj + (body?.trim() ? "\n\n" + body.trim() : "");
440
- return `${header}
441
- ${msg}`;
442
- }).join("\n\n---\n\n");
443
- }
444
- async function ingestGitLog(client, repo, opts = { limit: 300 }) {
445
- const log3 = opts.log ?? (() => {
446
- });
447
- const text = gitLogText(repo, opts.limit);
448
- if (!text) {
449
- log3("[gitlog] no commits found \u2014 skipping");
450
- return 0;
451
- }
452
- const repoName = repoNameOf(repo);
453
- const n = text.split("\n\n---\n\n").length;
454
- log3(`[gitlog] ingesting last ${n} commit messages for ${repoName} as ONE document \u2026`);
455
- try {
456
- const head = gitHeadSha(repo);
457
- await client.retain(
458
- text,
459
- `git commit-message history (last ${n}) for ${repoName}`,
460
- `gitlog:${repoName}`,
461
- ["source:git", "source:git-log", ...head ? [`gitlog-head:${head}`] : []],
462
- "gitlog"
463
- );
464
- log3(`[gitlog] done: ${n} commit messages ingested as 1 document under strategy 'gitlog'`);
465
- return 0;
466
- } catch (e) {
467
- log3(` ! gitlog ingest failed: ${e.message?.slice(0, 120)}`);
468
- return 1;
469
- }
470
- }
471
-
472
- // src/core/survey.ts
473
- import { spawn as realSpawn2 } from "child_process";
474
- import { accessSync, constants, existsSync } from "fs";
475
- import { homedir as homedir3 } from "os";
476
- import { delimiter, dirname as dirname3, join as join4 } from "path";
477
- import { fileURLToPath as fileURLToPath2 } from "url";
478
- var SURVEY_DOC_IDS = [
479
- "repository-component-map",
480
- "repository-core-concepts",
481
- "repository-conventions-and-patterns",
482
- "repository-tech-stack-and-features"
483
- ];
484
-
485
118
  // src/core/missions.ts
486
119
  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.";
487
120
  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.";
@@ -602,17 +235,64 @@ var CODING_BANK_TEMPLATE = {
602
235
  entity_labels: [KNOWLEDGE_LABELS],
603
236
  entities_allow_free_form: true
604
237
  }
605
- };
606
- var CODING_BANK_STRUCTURE = {
607
- version: "1",
608
- bank: {
609
- retain_strategies: RETAIN_STRATEGIES,
610
- entity_labels: [KNOWLEDGE_LABELS]
238
+ };
239
+ var CODING_BANK_STRUCTURE = {
240
+ version: "1",
241
+ bank: {
242
+ retain_strategies: RETAIN_STRATEGIES,
243
+ entity_labels: [KNOWLEDGE_LABELS]
244
+ }
245
+ };
246
+
247
+ // src/core/util.ts
248
+ var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
249
+ function semverGte(version, min) {
250
+ const parts = (v) => {
251
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
252
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
253
+ };
254
+ const a = version ? parts(version) : void 0;
255
+ const b = parts(min);
256
+ if (!a || !b) return false;
257
+ for (let i = 0; i < 3; i++) {
258
+ if (a[i] !== b[i]) return a[i] > b[i];
259
+ }
260
+ return true;
261
+ }
262
+ async function pool(items, n, fn, onError, onProgress) {
263
+ let i = 0, done = 0;
264
+ async function worker() {
265
+ while (i < items.length) {
266
+ const idx = i++;
267
+ try {
268
+ await fn(items[idx], idx);
269
+ } catch (e) {
270
+ onError?.(idx, e);
271
+ }
272
+ onProgress?.(++done, items.length);
273
+ }
611
274
  }
612
- };
275
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
276
+ }
613
277
 
614
278
  // src/core/hindsight.ts
615
279
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
280
+ var RateLimitedError = class extends Error {
281
+ constructor(retryAfterMs2) {
282
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
283
+ this.retryAfterMs = retryAfterMs2;
284
+ this.name = "RateLimitedError";
285
+ }
286
+ retryAfterMs;
287
+ code = "rate_limited";
288
+ };
289
+ function retryAfterMs(header) {
290
+ if (!header) return 0;
291
+ const secs = Number(header.trim());
292
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
293
+ const at = Date.parse(header);
294
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
295
+ }
616
296
  var KnowledgePagesUnavailableError = class extends Error {
617
297
  code = "knowledge_pages_unavailable";
618
298
  constructor() {
@@ -621,6 +301,10 @@ var KnowledgePagesUnavailableError = class extends Error {
621
301
  }
622
302
  };
623
303
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
304
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
305
+ var POLL_CYCLE_MS = 5e3;
306
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
307
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
624
308
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
625
309
  var HindsightClient = class {
626
310
  apiUrl;
@@ -633,12 +317,14 @@ var HindsightClient = class {
633
317
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
634
318
  idempotentRetain;
635
319
  log;
320
+ maxParallelRetains;
636
321
  constructor(o) {
637
322
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
638
323
  this.apiToken = o.apiToken;
639
324
  this.bank = o.bank;
640
325
  this.log = o.log ?? (() => {
641
326
  });
327
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
642
328
  }
643
329
  headers() {
644
330
  const h = { "Content-Type": "application/json" };
@@ -656,6 +342,8 @@ var HindsightClient = class {
656
342
  body: body ? JSON.stringify(body) : void 0,
657
343
  signal: AbortSignal.timeout(15e3)
658
344
  });
345
+ if (r.status === 429 && !tolerate.includes(429))
346
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
659
347
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
660
348
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
661
349
  return r;
@@ -787,7 +475,14 @@ var HindsightClient = class {
787
475
  return 0;
788
476
  }
789
477
  }
790
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
478
+ /**
479
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
480
+ *
481
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
482
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
483
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
484
+ * of hammering the next cycle 5s later.
485
+ */
791
486
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
792
487
  if (!ids.length) return;
793
488
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -795,23 +490,29 @@ var HindsightClient = class {
795
490
  const pending = new Set(ids);
796
491
  let failed = 0;
797
492
  while (pending.size && Date.now() - start < maxMs) {
798
- await Promise.all(
799
- [...pending].map(async (id) => {
800
- try {
801
- const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
802
- if (!r.ok) return;
803
- const st = ((await r.json()).status || "").toLowerCase();
804
- if (TERMINAL.has(st)) {
805
- pending.delete(id);
806
- if (st !== "completed") failed++;
807
- }
808
- } catch {
493
+ let backoffMs = POLL_CYCLE_MS;
494
+ await pool([...pending], this.maxParallelRetains, async (id) => {
495
+ try {
496
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
497
+ if (r.status === 429) {
498
+ backoffMs = Math.min(
499
+ RETRY_AFTER_CEILING_MS,
500
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
501
+ );
502
+ return;
809
503
  }
810
- })
811
- );
504
+ if (!r.ok) return;
505
+ const st = ((await r.json()).status || "").toLowerCase();
506
+ if (TERMINAL.has(st)) {
507
+ pending.delete(id);
508
+ if (st !== "completed") failed++;
509
+ }
510
+ } catch {
511
+ }
512
+ });
812
513
  if (pending.size) {
813
514
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
814
- await sleep(5e3);
515
+ await sleep(backoffMs);
815
516
  }
816
517
  }
817
518
  this.log(
@@ -974,70 +675,494 @@ var HindsightClient = class {
974
675
  updated++;
975
676
  }
976
677
  }
977
- this.log(
978
- `[bank] knowledge pages seeded on ${this.bank}: ${created} created, ${updated} re-synced, ${PAGES.length - created - updated} unchanged`
979
- );
678
+ this.log(
679
+ `[bank] knowledge pages seeded on ${this.bank}: ${created} created, ${updated} re-synced, ${PAGES.length - created - updated} unchanged`
680
+ );
681
+ }
682
+ /** URL/id-safe slug: lowercase, non-alphanumerics → "-", trim dashes, cap length; fallback "initiative". */
683
+ slugify(s) {
684
+ return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "initiative";
685
+ }
686
+ /**
687
+ * Active-path capture: register a major feature as a per-initiative page + a tagged marker memory.
688
+ * New initiative → creates a page under the Initiatives folder tagged `relatedPageId:<pageId>`.
689
+ * Enhancement (relatesToPageId) → no new page; only a marker accruing to the existing page.
690
+ */
691
+ async captureInitiative(args) {
692
+ let pageId = args.relatesToPageId;
693
+ if (!pageId) {
694
+ const folderId = await this.ensureFolder("Initiatives");
695
+ const r = await this.req("POST", this.bankUrl("/knowledge-base/pages"), {
696
+ name: args.title,
697
+ source_query: `Summarize the "${args.title}" initiative: what is being built or changed and why, and its current state \u2014 drawn from the project's memory.`,
698
+ parent_id: folderId,
699
+ tags: ["knowledge:feature-work"],
700
+ trigger: {
701
+ fact_types: ["world", "experience", "observation"],
702
+ refresh_after_consolidation: true
703
+ }
704
+ });
705
+ try {
706
+ const j = await r.json();
707
+ pageId = j.page_id ?? j.id;
708
+ } catch {
709
+ }
710
+ pageId ||= `initiative-${this.slugify(args.title)}`;
711
+ }
712
+ const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
713
+ const content = `${verb}: ${args.title}. ${args.summary}`;
714
+ const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
715
+ const tags = [
716
+ .../* @__PURE__ */ new Set([
717
+ ...args.stamp?.tags ?? [],
718
+ "knowledge:feature-work",
719
+ `relatedPageId:${pageId}`
720
+ ])
721
+ ];
722
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
723
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
724
+ metadata: args.stamp?.metadata
725
+ });
726
+ } else {
727
+ await this.retain(content, "initiative marker", markerId, tags, "document");
728
+ }
729
+ return { page_id: pageId };
730
+ }
731
+ /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
732
+ async ensureFolder(name) {
733
+ try {
734
+ const tree = await (await this.req("GET", this.bankUrl("/knowledge-base/tree"))).json();
735
+ const hit = (tree.roots || []).find(
736
+ (n) => n.kind === "folder" && (n.name || "").toLowerCase() === name.toLowerCase()
737
+ );
738
+ if (hit?.id) return hit.id;
739
+ } catch {
740
+ }
741
+ try {
742
+ const r = await this.req("POST", this.bankUrl("/knowledge-base/folders"), { name });
743
+ return (await r.json()).id;
744
+ } catch {
745
+ return void 0;
746
+ }
747
+ }
748
+ };
749
+
750
+ // src/core/retain-cursor.ts
751
+ import { createHash } from "crypto";
752
+
753
+ // src/core/uuid.ts
754
+ import { createHash as createHash2 } from "crypto";
755
+
756
+ // src/core/chat.ts
757
+ function withRefId(refId, turns, baseTs) {
758
+ return [{ role: "system", content: `REF-ID: ${refId}`, timestamp: baseTs }, ...turns];
759
+ }
760
+ async function ingestChats(client, sessions, opts = {}) {
761
+ const log3 = opts.log ?? (() => {
762
+ });
763
+ if (!sessions.length) {
764
+ log3("[chat] no sessions; skipping");
765
+ return 0;
766
+ }
767
+ log3(`[chat] ingesting ${sessions.length} chats (RAW, JSONL transcript \u2014 one turn per line) \u2026`);
768
+ const NOW = Date.now();
769
+ let failures = 0;
770
+ await pool(
771
+ sessions,
772
+ opts.concurrency ?? 8,
773
+ async (s, i) => {
774
+ const id = s.id || `s${i}`;
775
+ const stamp = opts.stampFor?.(id);
776
+ const sessBase = NOW - (sessions.length - 1 - i) * 36e5;
777
+ const baseIso = new Date(sessBase).toISOString();
778
+ const turns = withRefId(
779
+ `chat:${id}`,
780
+ (s.turns || []).map((t, j) => ({
781
+ role: t.role,
782
+ content: t.text,
783
+ timestamp: t.timestamp || new Date(sessBase + (j + 1) * 6e4).toISOString()
784
+ })),
785
+ baseIso
786
+ );
787
+ await client.retain(
788
+ turns.map((x) => JSON.stringify(x)).join("\n"),
789
+ "developer chat",
790
+ `chat:${id}`,
791
+ [.../* @__PURE__ */ new Set([...stamp?.tags ?? [], "source:chat"])],
792
+ "conversation",
793
+ {
794
+ timestamp: baseIso,
795
+ metadata: {
796
+ ...stamp?.metadata,
797
+ source: "chat",
798
+ chat: id,
799
+ ref_id: `chat:${id}`
800
+ }
801
+ }
802
+ );
803
+ },
804
+ (i, e) => {
805
+ failures++;
806
+ log3(` ! chat ${i} failed to enqueue: ${e.message?.slice(0, 120)}`);
807
+ }
808
+ );
809
+ log3(`[chat] done: ${sessions.length} chats ingested (JSONL) under strategy 'chat'`);
810
+ return failures;
811
+ }
812
+
813
+ // src/core/config.ts
814
+ import { readFileSync } from "fs";
815
+ import { homedir as homedir2 } from "os";
816
+ import { join as join3 } from "path";
817
+
818
+ // src/core/seed.ts
819
+ import { spawn as realSpawn } from "child_process";
820
+ import { dirname as dirname2, join as join2 } from "path";
821
+ import { fileURLToPath } from "url";
822
+ var DEFAULT_SEED_LIMIT = 300;
823
+
824
+ // src/core/config.ts
825
+ var CONFIG_PATH = process.env.HINDSIGHT_CONFIG || join3(homedir2(), ".hindsight", "coding-agent.json");
826
+ var DEFAULT_DAEMON_PORT = 9077;
827
+ var DEFAULT_DAEMON_IDLE_TIMEOUT = 300;
828
+ var DEFAULT_DAEMON_PROFILE = "coding-agent";
829
+ function resolveConfig(raw = {}) {
830
+ const serverMode = ["cloud", "self-hosted", "daemon"].includes(raw.serverMode) ? raw.serverMode : "cloud";
831
+ const apiPort = raw.apiPort || DEFAULT_DAEMON_PORT;
832
+ return {
833
+ serverMode,
834
+ // Daemon mode resolves the URL HERE rather than at each call site: every entry point already
835
+ // builds its client from cfg.apiUrl, so collapsing the mode into that one field means the
836
+ // daemon needs no plumbing through eight separate constructors.
837
+ apiUrl: serverMode === "daemon" ? `http://127.0.0.1:${apiPort}` : raw.apiUrl ?? "https://api.hindsight.vectorize.io",
838
+ apiToken: raw.apiToken || void 0,
839
+ apiPort,
840
+ daemonIdleTimeout: raw.daemonIdleTimeout ?? DEFAULT_DAEMON_IDLE_TIMEOUT,
841
+ daemonProfile: raw.daemonProfile || DEFAULT_DAEMON_PROFILE,
842
+ embedVersion: raw.embedVersion || void 0,
843
+ embedPackagePath: raw.embedPackagePath || void 0,
844
+ bankId: raw.bankId,
845
+ dynamicBankId: raw.dynamicBankId,
846
+ bankIdTemplate: raw.bankIdTemplate,
847
+ mapPathToBank: raw.mapPathToBank,
848
+ resolveWorktrees: raw.resolveWorktrees,
849
+ optInOnly: raw.optInOnly ?? false,
850
+ // Same shape as retainTags: a config typo must not become a path that silently approves nothing.
851
+ optInPaths: Array.isArray(raw.optInPaths) ? raw.optInPaths.filter((p) => typeof p === "string" && p.trim() !== "") : [],
852
+ harness: raw.harness ?? "opencode",
853
+ disabled: raw.disabled ?? false,
854
+ retainSessions: raw.retainSessions ?? true,
855
+ // opencode: write back by default (parity with hook-harness Stop)
856
+ maxParallelRetains: raw.maxParallelRetains || 10,
857
+ reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
858
+ autoReflect: raw.autoReflect ?? true,
859
+ pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
860
+ autoSeed: raw.autoSeed ?? true,
861
+ seedLimit: raw.seedLimit || DEFAULT_SEED_LIMIT,
862
+ codebaseSurvey: raw.codebaseSurvey ?? true,
863
+ surveyModel: raw.surveyModel || "haiku",
864
+ surveyBudgetUsd: raw.surveyBudgetUsd || 2,
865
+ surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
866
+ gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
867
+ // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
868
+ // nested object cannot reach the API as a tag and fail the whole retain.
869
+ retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
870
+ retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
871
+ Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
872
+ ) : {},
873
+ banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
874
+ logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
875
+ };
876
+ }
877
+ function readRaw(path) {
878
+ try {
879
+ return JSON.parse(readFileSync(path, "utf8"));
880
+ } catch (e) {
881
+ if (e?.code !== "ENOENT") {
882
+ console.error(`hindsight: ignoring invalid config at ${path}: ${e?.message || e}`);
883
+ }
884
+ return {};
885
+ }
886
+ }
887
+ function mergeRaw(a, b) {
888
+ const { harnesses: _drop, ...flat } = b;
889
+ return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
890
+ }
891
+ function applyLayer(raw, layer, harness) {
892
+ let out = mergeRaw(raw, layer);
893
+ const perHarness = harness ? layer.harnesses?.[harness] : void 0;
894
+ if (perHarness) out = mergeRaw(out, perHarness);
895
+ return out;
896
+ }
897
+ var ENV_KEYS = {
898
+ serverMode: "HINDSIGHT_SERVER_MODE",
899
+ apiUrl: "HINDSIGHT_API_URL",
900
+ apiToken: "HINDSIGHT_API_TOKEN",
901
+ // These four keep the names the old per-agent Claude Code plugin used, so a user migrating from
902
+ // it can carry their existing environment over unchanged.
903
+ apiPort: "HINDSIGHT_API_PORT",
904
+ daemonIdleTimeout: "HINDSIGHT_DAEMON_IDLE_TIMEOUT",
905
+ embedVersion: "HINDSIGHT_EMBED_VERSION",
906
+ embedPackagePath: "HINDSIGHT_EMBED_PACKAGE_PATH",
907
+ daemonProfile: "HINDSIGHT_DAEMON_PROFILE",
908
+ bankId: "HINDSIGHT_BANK_ID",
909
+ dynamicBankId: "HINDSIGHT_DYNAMIC_BANK_ID",
910
+ bankIdTemplate: "HINDSIGHT_BANK_ID_TEMPLATE",
911
+ resolveWorktrees: "HINDSIGHT_RESOLVE_WORKTREES",
912
+ optInOnly: "HINDSIGHT_OPT_IN_ONLY",
913
+ optInPaths: "HINDSIGHT_OPT_IN_PATHS",
914
+ harness: "HINDSIGHT_HARNESS",
915
+ disabled: "HINDSIGHT_DISABLED",
916
+ retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
917
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
918
+ reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
919
+ autoReflect: "HINDSIGHT_AUTO_REFLECT",
920
+ pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
921
+ autoSeed: "HINDSIGHT_AUTO_SEED",
922
+ seedLimit: "HINDSIGHT_SEED_LIMIT",
923
+ codebaseSurvey: "HINDSIGHT_CODEBASE_SURVEY",
924
+ surveyModel: "HINDSIGHT_SURVEY_MODEL",
925
+ surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
926
+ surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
927
+ logLevel: "HINDSIGHT_LOG_LEVEL",
928
+ gitIngest: "HINDSIGHT_GIT_INGEST",
929
+ // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
930
+ // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
931
+ retainTags: "HINDSIGHT_RETAIN_TAGS"
932
+ };
933
+ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
934
+ "dynamicBankId",
935
+ "resolveWorktrees",
936
+ "optInOnly",
937
+ "disabled",
938
+ "retainSessions",
939
+ "autoReflect",
940
+ "autoSeed",
941
+ "codebaseSurvey"
942
+ ]);
943
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags", "optInPaths"]);
944
+ var ENV_NUMBERS = /* @__PURE__ */ new Set([
945
+ "apiPort",
946
+ "daemonIdleTimeout",
947
+ "maxParallelRetains",
948
+ "reflectTimeoutMs",
949
+ "pageRefreshEveryTurns",
950
+ "seedLimit",
951
+ "surveyBudgetUsd",
952
+ "surveyRefreshCommits"
953
+ ]);
954
+ function readEnvConfig(env = process.env) {
955
+ const out = {};
956
+ for (const [key, name] of Object.entries(ENV_KEYS)) {
957
+ const value = env[name];
958
+ if (value === void 0 || value.trim() === "") continue;
959
+ if (ENV_BOOLEANS.has(key)) {
960
+ out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
961
+ } else if (ENV_LISTS.has(key)) {
962
+ const items = value.split(",").map((v) => v.trim()).filter(Boolean);
963
+ if (items.length) out[key] = items;
964
+ } else if (ENV_NUMBERS.has(key)) {
965
+ const n = Number(value);
966
+ if (Number.isFinite(n)) out[key] = n;
967
+ else console.error(`hindsight: ignoring ${name}=${value} \u2014 not a number`);
968
+ } else {
969
+ out[key] = value;
970
+ }
980
971
  }
981
- /** URL/id-safe slug: lowercase, non-alphanumerics → "-", trim dashes, cap length; fallback "initiative". */
982
- slugify(s) {
983
- return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "initiative";
972
+ return out;
973
+ }
974
+ function loadConfig(opts = {}) {
975
+ const o = typeof opts === "string" ? { path: opts } : opts;
976
+ const withEnv = applyLayer({}, readEnvConfig(), o.harness);
977
+ const raw = applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness);
978
+ if (!raw.harness && o.harness) raw.harness = o.harness;
979
+ return resolveConfig(raw);
980
+ }
981
+ var BANK_OVERRIDE_EXCLUDED = [
982
+ "bankId",
983
+ "bankIdTemplate",
984
+ "mapPathToBank",
985
+ "dynamicBankId",
986
+ "resolveWorktrees",
987
+ // Approval is decided BEFORE the bank is resolved, so a `banks.<id>` section naming these could
988
+ // only ever arrive too late to matter — strip them rather than let them read as effective.
989
+ "optInOnly",
990
+ "optInPaths",
991
+ "harness"
992
+ ];
993
+ function applyBankConfig(cfg2, resolvedId, directory) {
994
+ if (directory !== void 0 && !isOptedIn(cfg2, directory))
995
+ return { cfg: { ...cfg2, disabled: true }, bankId: resolvedId };
996
+ const section = cfg2.banks[resolvedId];
997
+ if (!section) return { cfg: cfg2, bankId: resolvedId };
998
+ const safe = { ...section };
999
+ for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1000
+ delete safe.banks;
1001
+ const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
1002
+ delete safe.bank;
1003
+ return { cfg: { ...cfg2, ...resolvePartial(cfg2, safe) }, bankId };
1004
+ }
1005
+ function resolvePartial(cfg2, patch) {
1006
+ const full = resolveConfig(patch);
1007
+ const out = {};
1008
+ for (const key of Object.keys(patch)) {
1009
+ if (key in full)
1010
+ out[key] = full[key];
984
1011
  }
985
- /**
986
- * Active-path capture: register a major feature as a per-initiative page + a tagged marker memory.
987
- * New initiative → creates a page under the Initiatives folder tagged `relatedPageId:<pageId>`.
988
- * Enhancement (relatesToPageId) → no new page; only a marker accruing to the existing page.
989
- */
990
- async captureInitiative(args) {
991
- let pageId = args.relatesToPageId;
992
- if (!pageId) {
993
- const folderId = await this.ensureFolder("Initiatives");
994
- const r = await this.req("POST", this.bankUrl("/knowledge-base/pages"), {
995
- name: args.title,
996
- source_query: `Summarize the "${args.title}" initiative: what is being built or changed and why, and its current state \u2014 drawn from the project's memory.`,
997
- parent_id: folderId,
998
- tags: ["knowledge:feature-work"],
999
- trigger: {
1000
- fact_types: ["world", "experience", "observation"],
1001
- refresh_after_consolidation: true
1002
- }
1003
- });
1004
- try {
1005
- const j = await r.json();
1006
- pageId = j.page_id ?? j.id;
1007
- } catch {
1012
+ return out;
1013
+ }
1014
+
1015
+ // src/core/git.ts
1016
+ import { execFileSync as execFileSync2 } from "child_process";
1017
+ import { resolve } from "path";
1018
+ var US = "";
1019
+ var RS = "";
1020
+ function git(repo, ...args) {
1021
+ return execFileSync2("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
1022
+ }
1023
+ function repoNameOf(repo) {
1024
+ return projectNameOf(resolve(repo));
1025
+ }
1026
+ function gitHeadSha(dir) {
1027
+ try {
1028
+ return git(dir, "rev-parse", "HEAD").trim() || null;
1029
+ } catch {
1030
+ return null;
1031
+ }
1032
+ }
1033
+ function commitsSince(dir, sinceSha) {
1034
+ try {
1035
+ const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
1036
+ return Number.isFinite(n) ? n : null;
1037
+ } catch {
1038
+ return null;
1039
+ }
1040
+ }
1041
+ async function retainCommit(client, repo, sha, repoName, stamp) {
1042
+ const [h, an, ae, aISO, cISO, subj, body] = git(
1043
+ repo,
1044
+ "show",
1045
+ "-s",
1046
+ `--format=%H${US}%an${US}%ae${US}%aI${US}%cI${US}%s${US}%b`,
1047
+ sha
1048
+ ).split(US);
1049
+ const msg = (subj + (body?.trim() ? "\n\n" + body.trim() : "")).trim();
1050
+ const diff = git(repo, "show", "--format=", sha);
1051
+ const content = `REF-ID: git:${sha.slice(0, 12)}
1052
+ Git commit ${sha.slice(0, 12)} in the ${repoName} repository (${an}, ${aISO}).
1053
+
1054
+ Message:
1055
+ ${msg}
1056
+
1057
+ Diff:
1058
+ ${diff}`;
1059
+ await client.retain(
1060
+ content,
1061
+ `git commit in ${repoName}`,
1062
+ `git:${sha}`,
1063
+ [.../* @__PURE__ */ new Set([...stamp?.tags ?? [], "source:git"])],
1064
+ "git",
1065
+ {
1066
+ timestamp: aISO,
1067
+ // the memory's timestamp is the commit's author date
1068
+ metadata: {
1069
+ ...stamp?.metadata,
1070
+ source: "git",
1071
+ repo: repoName,
1072
+ commit: h,
1073
+ short_sha: sha.slice(0, 12),
1074
+ author: an,
1075
+ author_email: ae,
1076
+ authored_at: aISO,
1077
+ committed_at: cISO,
1078
+ subject: subj
1008
1079
  }
1009
- pageId ||= `initiative-${this.slugify(args.title)}`;
1010
1080
  }
1011
- const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
1012
- const content = `${verb}: ${args.title}. ${args.summary}`;
1013
- const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
1014
- await this.retain(
1015
- content,
1016
- "initiative marker",
1017
- markerId,
1018
- ["knowledge:feature-work", `relatedPageId:${pageId}`],
1019
- "document"
1081
+ );
1082
+ }
1083
+ function gitLogText(repo, limit) {
1084
+ let raw;
1085
+ try {
1086
+ raw = git(
1087
+ repo,
1088
+ "log",
1089
+ `-n`,
1090
+ String(limit),
1091
+ "--no-merges",
1092
+ "--date=short",
1093
+ `--format=%h${US}%ad${US}%an${US}%s${US}%b${RS}`
1020
1094
  );
1021
- return { page_id: pageId };
1095
+ } catch {
1096
+ return "";
1022
1097
  }
1023
- /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
1024
- async ensureFolder(name) {
1025
- try {
1026
- const tree = await (await this.req("GET", this.bankUrl("/knowledge-base/tree"))).json();
1027
- const hit = (tree.roots || []).find(
1028
- (n) => n.kind === "folder" && (n.name || "").toLowerCase() === name.toLowerCase()
1098
+ return raw.split(RS).map((rec) => rec.trim()).filter(Boolean).map((rec) => {
1099
+ const [sha, date, author, subj, body] = rec.split(US);
1100
+ const header = `${sha} ${date} ${author}`;
1101
+ const msg = subj + (body?.trim() ? "\n\n" + body.trim() : "");
1102
+ return `${header}
1103
+ ${msg}`;
1104
+ }).join("\n\n---\n\n");
1105
+ }
1106
+ async function ingestGitLog(client, repo, opts = { limit: 300 }) {
1107
+ const log3 = opts.log ?? (() => {
1108
+ });
1109
+ const text = gitLogText(repo, opts.limit);
1110
+ if (!text) {
1111
+ log3("[gitlog] no commits found \u2014 skipping");
1112
+ return 0;
1113
+ }
1114
+ const repoName = repoNameOf(repo);
1115
+ const n = text.split("\n\n---\n\n").length;
1116
+ log3(`[gitlog] ingesting last ${n} commit messages for ${repoName} as ONE document \u2026`);
1117
+ try {
1118
+ const head = gitHeadSha(repo);
1119
+ const stamp = opts.stampFor?.();
1120
+ const tags = [
1121
+ .../* @__PURE__ */ new Set([
1122
+ ...stamp?.tags ?? [],
1123
+ "source:git",
1124
+ "source:git-log",
1125
+ ...head ? [`gitlog-head:${head}`] : []
1126
+ ])
1127
+ ];
1128
+ if (Object.keys(stamp?.metadata ?? {}).length) {
1129
+ await client.retain(
1130
+ text,
1131
+ `git commit-message history (last ${n}) for ${repoName}`,
1132
+ `gitlog:${repoName}`,
1133
+ tags,
1134
+ "gitlog",
1135
+ { metadata: stamp?.metadata }
1136
+ );
1137
+ } else {
1138
+ await client.retain(
1139
+ text,
1140
+ `git commit-message history (last ${n}) for ${repoName}`,
1141
+ `gitlog:${repoName}`,
1142
+ tags,
1143
+ "gitlog"
1029
1144
  );
1030
- if (hit?.id) return hit.id;
1031
- } catch {
1032
- }
1033
- try {
1034
- const r = await this.req("POST", this.bankUrl("/knowledge-base/folders"), { name });
1035
- return (await r.json()).id;
1036
- } catch {
1037
- return void 0;
1038
1145
  }
1146
+ log3(`[gitlog] done: ${n} commit messages ingested as 1 document under strategy 'gitlog'`);
1147
+ return 0;
1148
+ } catch (e) {
1149
+ log3(` ! gitlog ingest failed: ${e.message?.slice(0, 120)}`);
1150
+ return 1;
1039
1151
  }
1040
- };
1152
+ }
1153
+
1154
+ // src/core/survey.ts
1155
+ import { spawn as realSpawn2 } from "child_process";
1156
+ import { accessSync, constants, existsSync as existsSync2 } from "fs";
1157
+ import { homedir as homedir3 } from "os";
1158
+ import { delimiter, dirname as dirname3, join as join4 } from "path";
1159
+ import { fileURLToPath as fileURLToPath2 } from "url";
1160
+ var SURVEY_DOC_IDS = [
1161
+ "repository-component-map",
1162
+ "repository-core-concepts",
1163
+ "repository-conventions-and-patterns",
1164
+ "repository-tech-stack-and-features"
1165
+ ];
1041
1166
 
1042
1167
  // src/core/status.ts
1043
1168
  import { execFileSync as execFileSync3 } from "child_process";
@@ -1066,6 +1191,8 @@ var HARNESS_NAMES = [
1066
1191
  "kilo",
1067
1192
  // Cline CLI loads dist/cline.js through its native plugin manager; file hooks cannot inject.
1068
1193
  "cline-cli",
1194
+ // Prime Agent loads dist/prime-agent.js as an extension (src/prime-agent.ts); no hook binary.
1195
+ "prime-agent",
1069
1196
  "claude-code",
1070
1197
  "cursor-cli",
1071
1198
  "codex",
@@ -1085,8 +1212,8 @@ var HOOK_BINS = {
1085
1212
  // more hook harnesses: add a HookSpec entry point (see src/cursor-hook.ts) + a registration here.
1086
1213
  };
1087
1214
  async function getHarness(name) {
1088
- if (name === "opencode" || name === "kilo" || name === "cline-cli") {
1089
- const entry = name === "opencode" ? "src/index.ts" : name === "kilo" ? "src/kilo.ts" : "src/cline.ts";
1215
+ if (name === "opencode" || name === "kilo" || name === "cline-cli" || name === "prime-agent") {
1216
+ const entry = name === "opencode" ? "src/index.ts" : name === "kilo" ? "src/kilo.ts" : name === "cline-cli" ? "src/cline.ts" : "src/prime-agent.ts";
1090
1217
  return noRuntimeAdapter(
1091
1218
  name,
1092
1219
  `${name}'s runtime is built by ${entry} (the ${name} plugin entrypoint), not via the harness registry`
@@ -1150,9 +1277,55 @@ function diag(harness, event, extra = {}) {
1150
1277
  }
1151
1278
  }
1152
1279
 
1280
+ // src/core/retain-stamp.ts
1281
+ import { basename as basename2 } from "path";
1282
+ var RESERVED_TAG_PREFIX = /^(source|harness):/;
1283
+ function resolversFor(ctx) {
1284
+ return {
1285
+ // Worktree-aware like the bank id, so every linked worktree of a repo stamps the SAME name —
1286
+ // otherwise a shared bank ends up with `project:app` and `project:app-wt2` for one repository.
1287
+ gitProject: () => projectNameOf(ctx.directory),
1288
+ project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
1289
+ harness: () => ctx.harness,
1290
+ bankId: () => ctx.bankId,
1291
+ sessionId: () => ctx.sessionId ?? "unknown",
1292
+ timestamp: () => (/* @__PURE__ */ new Date()).toISOString(),
1293
+ channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
1294
+ user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
1295
+ };
1296
+ }
1297
+ function buildRetainStamp(cfg2, ctx) {
1298
+ const hasTags = Boolean(cfg2.retainTags?.length);
1299
+ const hasMetadata = Boolean(cfg2.retainMetadata && Object.keys(cfg2.retainMetadata).length);
1300
+ if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
1301
+ const base = resolversFor(ctx);
1302
+ const cache = /* @__PURE__ */ new Map();
1303
+ const resolvers = Object.fromEntries(
1304
+ Object.entries(base).map(([name, resolve2]) => [
1305
+ name,
1306
+ () => {
1307
+ const hit = cache.get(name);
1308
+ if (hit !== void 0) return hit;
1309
+ const value = resolve2();
1310
+ cache.set(name, value);
1311
+ return value;
1312
+ }
1313
+ ])
1314
+ );
1315
+ const tags = (cfg2.retainTags ?? []).map((t) => applyTemplate(t, resolvers, "retainTags").trim()).filter(Boolean).filter((t) => {
1316
+ if (!RESERVED_TAG_PREFIX.test(t)) return true;
1317
+ log.warn("retain-stamp", "ignoring reserved retainTags entry", { tag: t });
1318
+ return false;
1319
+ });
1320
+ const metadata = {};
1321
+ for (const [key, value] of Object.entries(cfg2.retainMetadata ?? {})) {
1322
+ metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
1323
+ }
1324
+ return { tags, metadata };
1325
+ }
1326
+
1153
1327
  // src/deepen.ts
1154
1328
  var DIFF_BATCH = 50;
1155
- var CONCURRENCY = 4;
1156
1329
  var LOCK_STALE_MS = 30 * 60 * 1e3;
1157
1330
  function arg(name, def) {
1158
1331
  const i = process.argv.indexOf(`--${name}`);
@@ -1162,7 +1335,7 @@ function arg(name, def) {
1162
1335
  var REPO = arg("repo");
1163
1336
  var cfg0 = loadConfig({ harness: arg("harness") ?? void 0, path: arg("config") });
1164
1337
  var BANK = arg("bank") ?? (REPO ? deriveBankId(cfg0, REPO, arg("harness") ?? cfg0.harness) : cfg0.bankId);
1165
- var resolved0 = BANK ? applyBankConfig(cfg0, BANK) : { cfg: cfg0, bankId: BANK };
1338
+ var resolved0 = BANK ? applyBankConfig(cfg0, BANK, REPO ?? void 0) : { cfg: cfg0, bankId: BANK };
1166
1339
  var cfg = resolved0.cfg;
1167
1340
  var FINAL_BANK = resolved0.bankId ?? BANK;
1168
1341
  if (cfg.disabled) {
@@ -1226,9 +1399,16 @@ async function main() {
1226
1399
  apiUrl: API_URL,
1227
1400
  apiToken: API_TOKEN,
1228
1401
  bank: FINAL_BANK,
1402
+ maxParallelRetains: cfg.maxParallelRetains,
1229
1403
  log: log2
1230
1404
  });
1231
1405
  log2(`deepen -> ${client.apiUrl} bank=${FINAL_BANK} harness=${harness.name}`);
1406
+ const stampFor = (sessionId) => buildRetainStamp(cfg, {
1407
+ directory: REPO,
1408
+ harness: HARNESS,
1409
+ bankId: FINAL_BANK,
1410
+ sessionId
1411
+ });
1232
1412
  await client.configureBank();
1233
1413
  if (client.knowledgePagesSupported === false) {
1234
1414
  diag(harness.name, "knowledge_pages_unavailable", {
@@ -1242,7 +1422,11 @@ async function main() {
1242
1422
  const sessions = all.filter((s, i) => !chatIds.has(`chat:${s.id || `s${i}`}`));
1243
1423
  if (all.length !== sessions.length)
1244
1424
  log2(`[chat] ${all.length - sessions.length} conversations already ingested \u2014 skipping those`);
1245
- const chatFails = await ingestChats(client, sessions, { concurrency: CONCURRENCY, log: log2 });
1425
+ const chatFails = await ingestChats(client, sessions, {
1426
+ concurrency: cfg.maxParallelRetains,
1427
+ log: log2,
1428
+ stampFor
1429
+ });
1246
1430
  let gitFails = 0;
1247
1431
  if (GIT_INGEST === "none") {
1248
1432
  log2("[git] gitIngest=none \u2014 git ingestion disabled");
@@ -1252,7 +1436,7 @@ async function main() {
1252
1436
  if (gitlogCurrent) {
1253
1437
  log2("[gitlog] current with HEAD \u2014 skipping");
1254
1438
  } else {
1255
- gitFails += await ingestGitLog(client, REPO, { limit: GITLOG_LIMIT, log: log2 });
1439
+ gitFails += await ingestGitLog(client, REPO, { limit: GITLOG_LIMIT, log: log2, stampFor });
1256
1440
  }
1257
1441
  try {
1258
1442
  const canonical = `gitlog:${repoNameOf(REPO)}`;
@@ -1277,8 +1461,8 @@ async function main() {
1277
1461
  log2(`[deepen] ingesting ${shas.length} commits with full diffs (newest first) \u2026`);
1278
1462
  await pool(
1279
1463
  shas,
1280
- CONCURRENCY,
1281
- (sha) => retainCommit(client, REPO, sha, repoName),
1464
+ cfg.maxParallelRetains,
1465
+ (sha) => retainCommit(client, REPO, sha, repoName, stampFor()),
1282
1466
  () => {
1283
1467
  gitFails++;
1284
1468
  }
@@ -1304,12 +1488,19 @@ async function main() {
1304
1488
  if (behind !== null && (!best || behind < best.behind)) best = { id, sha, behind };
1305
1489
  }
1306
1490
  if (best) {
1491
+ const stamp = stampFor();
1492
+ const content = `\u2705 Codebase survey completed \u2014 baseline commit ${best.sha.slice(0, 12)}. (Internal marker: no memories are extracted from this document.)`;
1493
+ const tags = [.../* @__PURE__ */ new Set([...stamp.tags, "source:survey-baseline", "survey-state:done"])];
1307
1494
  await client.retain(
1308
- `\u2705 Codebase survey completed \u2014 baseline commit ${best.sha.slice(0, 12)}. (Internal marker: no memories are extracted from this document.)`,
1495
+ content,
1309
1496
  "hindsight codebase-survey baseline",
1310
1497
  best.id,
1311
- ["source:survey-baseline", "survey-state:done"],
1312
- "survey"
1498
+ tags,
1499
+ "survey",
1500
+ {
1501
+ // `retain` only sets metadata when it is truthy, so an empty stamp sends none.
1502
+ metadata: Object.keys(stamp.metadata).length ? stamp.metadata : void 0
1503
+ }
1313
1504
  );
1314
1505
  log2(`[survey] marker ${best.id} flipped to completed`);
1315
1506
  }