@vectorize-io/hindsight-coding-agents 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/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,12 +47,32 @@ 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);
55
76
  }
56
77
  function mapLookup(map, directory) {
57
78
  const cwd = normalize(directory);
@@ -72,7 +93,7 @@ function deriveBankId(config, directory, harness = "coding") {
72
93
  if (!dynamic) return config.bankId || DEFAULT_BANK_NAME;
73
94
  const resolvers = {
74
95
  harness: () => harness,
75
- project: () => directory ? basename(directory) : "unknown",
96
+ project: () => dirName(directory),
76
97
  gitProject: () => gitProjectName(directory, config.resolveWorktrees ?? true),
77
98
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
78
99
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -80,408 +101,6 @@ function deriveBankId(config, directory, harness = "coding") {
80
101
  return applyTemplate(config.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
81
102
  }
82
103
 
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
104
  // src/core/missions.ts
486
105
  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
106
  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 +221,64 @@ var CODING_BANK_TEMPLATE = {
602
221
  entity_labels: [KNOWLEDGE_LABELS],
603
222
  entities_allow_free_form: true
604
223
  }
605
- };
606
- var CODING_BANK_STRUCTURE = {
607
- version: "1",
608
- bank: {
609
- retain_strategies: RETAIN_STRATEGIES,
610
- entity_labels: [KNOWLEDGE_LABELS]
224
+ };
225
+ var CODING_BANK_STRUCTURE = {
226
+ version: "1",
227
+ bank: {
228
+ retain_strategies: RETAIN_STRATEGIES,
229
+ entity_labels: [KNOWLEDGE_LABELS]
230
+ }
231
+ };
232
+
233
+ // src/core/util.ts
234
+ var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
235
+ function semverGte(version, min) {
236
+ const parts = (v) => {
237
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
238
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
239
+ };
240
+ const a = version ? parts(version) : void 0;
241
+ const b = parts(min);
242
+ if (!a || !b) return false;
243
+ for (let i = 0; i < 3; i++) {
244
+ if (a[i] !== b[i]) return a[i] > b[i];
245
+ }
246
+ return true;
247
+ }
248
+ async function pool(items, n, fn, onError, onProgress) {
249
+ let i = 0, done = 0;
250
+ async function worker() {
251
+ while (i < items.length) {
252
+ const idx = i++;
253
+ try {
254
+ await fn(items[idx], idx);
255
+ } catch (e) {
256
+ onError?.(idx, e);
257
+ }
258
+ onProgress?.(++done, items.length);
259
+ }
611
260
  }
612
- };
261
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
262
+ }
613
263
 
614
264
  // src/core/hindsight.ts
615
265
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
266
+ var RateLimitedError = class extends Error {
267
+ constructor(retryAfterMs2) {
268
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
269
+ this.retryAfterMs = retryAfterMs2;
270
+ this.name = "RateLimitedError";
271
+ }
272
+ retryAfterMs;
273
+ code = "rate_limited";
274
+ };
275
+ function retryAfterMs(header) {
276
+ if (!header) return 0;
277
+ const secs = Number(header.trim());
278
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
279
+ const at = Date.parse(header);
280
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
281
+ }
616
282
  var KnowledgePagesUnavailableError = class extends Error {
617
283
  code = "knowledge_pages_unavailable";
618
284
  constructor() {
@@ -621,6 +287,10 @@ var KnowledgePagesUnavailableError = class extends Error {
621
287
  }
622
288
  };
623
289
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
290
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
291
+ var POLL_CYCLE_MS = 5e3;
292
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
293
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
624
294
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
625
295
  var HindsightClient = class {
626
296
  apiUrl;
@@ -633,12 +303,14 @@ var HindsightClient = class {
633
303
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
634
304
  idempotentRetain;
635
305
  log;
306
+ maxParallelRetains;
636
307
  constructor(o) {
637
308
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
638
309
  this.apiToken = o.apiToken;
639
310
  this.bank = o.bank;
640
311
  this.log = o.log ?? (() => {
641
312
  });
313
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
642
314
  }
643
315
  headers() {
644
316
  const h = { "Content-Type": "application/json" };
@@ -656,6 +328,8 @@ var HindsightClient = class {
656
328
  body: body ? JSON.stringify(body) : void 0,
657
329
  signal: AbortSignal.timeout(15e3)
658
330
  });
331
+ if (r.status === 429 && !tolerate.includes(429))
332
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
659
333
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
660
334
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
661
335
  return r;
@@ -787,7 +461,14 @@ var HindsightClient = class {
787
461
  return 0;
788
462
  }
789
463
  }
790
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
464
+ /**
465
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
466
+ *
467
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
468
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
469
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
470
+ * of hammering the next cycle 5s later.
471
+ */
791
472
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
792
473
  if (!ids.length) return;
793
474
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -795,23 +476,29 @@ var HindsightClient = class {
795
476
  const pending = new Set(ids);
796
477
  let failed = 0;
797
478
  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 {
479
+ let backoffMs = POLL_CYCLE_MS;
480
+ await pool([...pending], this.maxParallelRetains, async (id) => {
481
+ try {
482
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
483
+ if (r.status === 429) {
484
+ backoffMs = Math.min(
485
+ RETRY_AFTER_CEILING_MS,
486
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
487
+ );
488
+ return;
809
489
  }
810
- })
811
- );
490
+ if (!r.ok) return;
491
+ const st = ((await r.json()).status || "").toLowerCase();
492
+ if (TERMINAL.has(st)) {
493
+ pending.delete(id);
494
+ if (st !== "completed") failed++;
495
+ }
496
+ } catch {
497
+ }
498
+ });
812
499
  if (pending.size) {
813
500
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
814
- await sleep(5e3);
501
+ await sleep(backoffMs);
815
502
  }
816
503
  }
817
504
  this.log(
@@ -974,70 +661,482 @@ var HindsightClient = class {
974
661
  updated++;
975
662
  }
976
663
  }
977
- this.log(
978
- `[bank] knowledge pages seeded on ${this.bank}: ${created} created, ${updated} re-synced, ${PAGES.length - created - updated} unchanged`
979
- );
664
+ this.log(
665
+ `[bank] knowledge pages seeded on ${this.bank}: ${created} created, ${updated} re-synced, ${PAGES.length - created - updated} unchanged`
666
+ );
667
+ }
668
+ /** URL/id-safe slug: lowercase, non-alphanumerics → "-", trim dashes, cap length; fallback "initiative". */
669
+ slugify(s) {
670
+ return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "initiative";
671
+ }
672
+ /**
673
+ * Active-path capture: register a major feature as a per-initiative page + a tagged marker memory.
674
+ * New initiative → creates a page under the Initiatives folder tagged `relatedPageId:<pageId>`.
675
+ * Enhancement (relatesToPageId) → no new page; only a marker accruing to the existing page.
676
+ */
677
+ async captureInitiative(args) {
678
+ let pageId = args.relatesToPageId;
679
+ if (!pageId) {
680
+ const folderId = await this.ensureFolder("Initiatives");
681
+ const r = await this.req("POST", this.bankUrl("/knowledge-base/pages"), {
682
+ name: args.title,
683
+ 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.`,
684
+ parent_id: folderId,
685
+ tags: ["knowledge:feature-work"],
686
+ trigger: {
687
+ fact_types: ["world", "experience", "observation"],
688
+ refresh_after_consolidation: true
689
+ }
690
+ });
691
+ try {
692
+ const j = await r.json();
693
+ pageId = j.page_id ?? j.id;
694
+ } catch {
695
+ }
696
+ pageId ||= `initiative-${this.slugify(args.title)}`;
697
+ }
698
+ const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
699
+ const content = `${verb}: ${args.title}. ${args.summary}`;
700
+ const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
701
+ const tags = [
702
+ .../* @__PURE__ */ new Set([
703
+ ...args.stamp?.tags ?? [],
704
+ "knowledge:feature-work",
705
+ `relatedPageId:${pageId}`
706
+ ])
707
+ ];
708
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
709
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
710
+ metadata: args.stamp?.metadata
711
+ });
712
+ } else {
713
+ await this.retain(content, "initiative marker", markerId, tags, "document");
714
+ }
715
+ return { page_id: pageId };
716
+ }
717
+ /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
718
+ async ensureFolder(name) {
719
+ try {
720
+ const tree = await (await this.req("GET", this.bankUrl("/knowledge-base/tree"))).json();
721
+ const hit = (tree.roots || []).find(
722
+ (n) => n.kind === "folder" && (n.name || "").toLowerCase() === name.toLowerCase()
723
+ );
724
+ if (hit?.id) return hit.id;
725
+ } catch {
726
+ }
727
+ try {
728
+ const r = await this.req("POST", this.bankUrl("/knowledge-base/folders"), { name });
729
+ return (await r.json()).id;
730
+ } catch {
731
+ return void 0;
732
+ }
733
+ }
734
+ };
735
+
736
+ // src/core/retain-cursor.ts
737
+ import { createHash } from "crypto";
738
+
739
+ // src/core/uuid.ts
740
+ import { createHash as createHash2 } from "crypto";
741
+
742
+ // src/core/chat.ts
743
+ function withRefId(refId, turns, baseTs) {
744
+ return [{ role: "system", content: `REF-ID: ${refId}`, timestamp: baseTs }, ...turns];
745
+ }
746
+ async function ingestChats(client, sessions, opts = {}) {
747
+ const log3 = opts.log ?? (() => {
748
+ });
749
+ if (!sessions.length) {
750
+ log3("[chat] no sessions; skipping");
751
+ return 0;
752
+ }
753
+ log3(`[chat] ingesting ${sessions.length} chats (RAW, JSONL transcript \u2014 one turn per line) \u2026`);
754
+ const NOW = Date.now();
755
+ let failures = 0;
756
+ await pool(
757
+ sessions,
758
+ opts.concurrency ?? 8,
759
+ async (s, i) => {
760
+ const id = s.id || `s${i}`;
761
+ const stamp = opts.stampFor?.(id);
762
+ const sessBase = NOW - (sessions.length - 1 - i) * 36e5;
763
+ const baseIso = new Date(sessBase).toISOString();
764
+ const turns = withRefId(
765
+ `chat:${id}`,
766
+ (s.turns || []).map((t, j) => ({
767
+ role: t.role,
768
+ content: t.text,
769
+ timestamp: t.timestamp || new Date(sessBase + (j + 1) * 6e4).toISOString()
770
+ })),
771
+ baseIso
772
+ );
773
+ await client.retain(
774
+ turns.map((x) => JSON.stringify(x)).join("\n"),
775
+ "developer chat",
776
+ `chat:${id}`,
777
+ [.../* @__PURE__ */ new Set([...stamp?.tags ?? [], "source:chat"])],
778
+ "conversation",
779
+ {
780
+ timestamp: baseIso,
781
+ metadata: {
782
+ ...stamp?.metadata,
783
+ source: "chat",
784
+ chat: id,
785
+ ref_id: `chat:${id}`
786
+ }
787
+ }
788
+ );
789
+ },
790
+ (i, e) => {
791
+ failures++;
792
+ log3(` ! chat ${i} failed to enqueue: ${e.message?.slice(0, 120)}`);
793
+ }
794
+ );
795
+ log3(`[chat] done: ${sessions.length} chats ingested (JSONL) under strategy 'chat'`);
796
+ return failures;
797
+ }
798
+
799
+ // src/core/config.ts
800
+ import { readFileSync } from "fs";
801
+ import { homedir as homedir2 } from "os";
802
+ import { join as join3 } from "path";
803
+
804
+ // src/core/seed.ts
805
+ import { spawn as realSpawn } from "child_process";
806
+ import { dirname as dirname2, join as join2 } from "path";
807
+ import { fileURLToPath } from "url";
808
+ var DEFAULT_SEED_LIMIT = 300;
809
+
810
+ // src/core/config.ts
811
+ var CONFIG_PATH = process.env.HINDSIGHT_CONFIG || join3(homedir2(), ".hindsight", "coding-agent.json");
812
+ var DEFAULT_DAEMON_PORT = 9077;
813
+ var DEFAULT_DAEMON_IDLE_TIMEOUT = 300;
814
+ var DEFAULT_DAEMON_PROFILE = "coding-agent";
815
+ function resolveConfig(raw = {}) {
816
+ const serverMode = ["cloud", "self-hosted", "daemon"].includes(raw.serverMode) ? raw.serverMode : "cloud";
817
+ const apiPort = raw.apiPort || DEFAULT_DAEMON_PORT;
818
+ return {
819
+ serverMode,
820
+ // Daemon mode resolves the URL HERE rather than at each call site: every entry point already
821
+ // builds its client from cfg.apiUrl, so collapsing the mode into that one field means the
822
+ // daemon needs no plumbing through eight separate constructors.
823
+ apiUrl: serverMode === "daemon" ? `http://127.0.0.1:${apiPort}` : raw.apiUrl ?? "https://api.hindsight.vectorize.io",
824
+ apiToken: raw.apiToken || void 0,
825
+ apiPort,
826
+ daemonIdleTimeout: raw.daemonIdleTimeout ?? DEFAULT_DAEMON_IDLE_TIMEOUT,
827
+ daemonProfile: raw.daemonProfile || DEFAULT_DAEMON_PROFILE,
828
+ embedVersion: raw.embedVersion || void 0,
829
+ embedPackagePath: raw.embedPackagePath || void 0,
830
+ bankId: raw.bankId,
831
+ dynamicBankId: raw.dynamicBankId,
832
+ bankIdTemplate: raw.bankIdTemplate,
833
+ mapPathToBank: raw.mapPathToBank,
834
+ resolveWorktrees: raw.resolveWorktrees,
835
+ harness: raw.harness ?? "opencode",
836
+ disabled: raw.disabled ?? false,
837
+ retainSessions: raw.retainSessions ?? true,
838
+ // opencode: write back by default (parity with hook-harness Stop)
839
+ maxParallelRetains: raw.maxParallelRetains || 10,
840
+ reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
841
+ autoReflect: raw.autoReflect ?? true,
842
+ pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
843
+ autoSeed: raw.autoSeed ?? true,
844
+ seedLimit: raw.seedLimit || DEFAULT_SEED_LIMIT,
845
+ codebaseSurvey: raw.codebaseSurvey ?? true,
846
+ surveyModel: raw.surveyModel || "haiku",
847
+ surveyBudgetUsd: raw.surveyBudgetUsd || 2,
848
+ surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
849
+ gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
850
+ // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
851
+ // nested object cannot reach the API as a tag and fail the whole retain.
852
+ retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
853
+ retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
854
+ Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
855
+ ) : {},
856
+ banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
857
+ logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
858
+ };
859
+ }
860
+ function readRaw(path) {
861
+ try {
862
+ return JSON.parse(readFileSync(path, "utf8"));
863
+ } catch (e) {
864
+ if (e?.code !== "ENOENT") {
865
+ console.error(`hindsight: ignoring invalid config at ${path}: ${e?.message || e}`);
866
+ }
867
+ return {};
868
+ }
869
+ }
870
+ function mergeRaw(a, b) {
871
+ const { harnesses: _drop, ...flat } = b;
872
+ return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
873
+ }
874
+ function applyLayer(raw, layer, harness) {
875
+ let out = mergeRaw(raw, layer);
876
+ const perHarness = harness ? layer.harnesses?.[harness] : void 0;
877
+ if (perHarness) out = mergeRaw(out, perHarness);
878
+ return out;
879
+ }
880
+ var ENV_KEYS = {
881
+ serverMode: "HINDSIGHT_SERVER_MODE",
882
+ apiUrl: "HINDSIGHT_API_URL",
883
+ apiToken: "HINDSIGHT_API_TOKEN",
884
+ // These four keep the names the old per-agent Claude Code plugin used, so a user migrating from
885
+ // it can carry their existing environment over unchanged.
886
+ apiPort: "HINDSIGHT_API_PORT",
887
+ daemonIdleTimeout: "HINDSIGHT_DAEMON_IDLE_TIMEOUT",
888
+ embedVersion: "HINDSIGHT_EMBED_VERSION",
889
+ embedPackagePath: "HINDSIGHT_EMBED_PACKAGE_PATH",
890
+ daemonProfile: "HINDSIGHT_DAEMON_PROFILE",
891
+ bankId: "HINDSIGHT_BANK_ID",
892
+ dynamicBankId: "HINDSIGHT_DYNAMIC_BANK_ID",
893
+ bankIdTemplate: "HINDSIGHT_BANK_ID_TEMPLATE",
894
+ resolveWorktrees: "HINDSIGHT_RESOLVE_WORKTREES",
895
+ harness: "HINDSIGHT_HARNESS",
896
+ disabled: "HINDSIGHT_DISABLED",
897
+ retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
898
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
899
+ reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
900
+ autoReflect: "HINDSIGHT_AUTO_REFLECT",
901
+ pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
902
+ autoSeed: "HINDSIGHT_AUTO_SEED",
903
+ seedLimit: "HINDSIGHT_SEED_LIMIT",
904
+ codebaseSurvey: "HINDSIGHT_CODEBASE_SURVEY",
905
+ surveyModel: "HINDSIGHT_SURVEY_MODEL",
906
+ surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
907
+ surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
908
+ logLevel: "HINDSIGHT_LOG_LEVEL",
909
+ gitIngest: "HINDSIGHT_GIT_INGEST",
910
+ // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
911
+ // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
912
+ retainTags: "HINDSIGHT_RETAIN_TAGS"
913
+ };
914
+ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
915
+ "dynamicBankId",
916
+ "resolveWorktrees",
917
+ "disabled",
918
+ "retainSessions",
919
+ "autoReflect",
920
+ "autoSeed",
921
+ "codebaseSurvey"
922
+ ]);
923
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
924
+ var ENV_NUMBERS = /* @__PURE__ */ new Set([
925
+ "apiPort",
926
+ "daemonIdleTimeout",
927
+ "maxParallelRetains",
928
+ "reflectTimeoutMs",
929
+ "pageRefreshEveryTurns",
930
+ "seedLimit",
931
+ "surveyBudgetUsd",
932
+ "surveyRefreshCommits"
933
+ ]);
934
+ function readEnvConfig(env = process.env) {
935
+ const out = {};
936
+ for (const [key, name] of Object.entries(ENV_KEYS)) {
937
+ const value = env[name];
938
+ if (value === void 0 || value.trim() === "") continue;
939
+ if (ENV_BOOLEANS.has(key)) {
940
+ out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
941
+ } else if (ENV_LISTS.has(key)) {
942
+ const items = value.split(",").map((v) => v.trim()).filter(Boolean);
943
+ if (items.length) out[key] = items;
944
+ } else if (ENV_NUMBERS.has(key)) {
945
+ const n = Number(value);
946
+ if (Number.isFinite(n)) out[key] = n;
947
+ else console.error(`hindsight: ignoring ${name}=${value} \u2014 not a number`);
948
+ } else {
949
+ out[key] = value;
950
+ }
980
951
  }
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";
952
+ return out;
953
+ }
954
+ function loadConfig(opts = {}) {
955
+ const o = typeof opts === "string" ? { path: opts } : opts;
956
+ const withEnv = applyLayer({}, readEnvConfig(), o.harness);
957
+ const raw = applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness);
958
+ if (!raw.harness && o.harness) raw.harness = o.harness;
959
+ return resolveConfig(raw);
960
+ }
961
+ var BANK_OVERRIDE_EXCLUDED = [
962
+ "bankId",
963
+ "bankIdTemplate",
964
+ "mapPathToBank",
965
+ "dynamicBankId",
966
+ "resolveWorktrees",
967
+ "harness"
968
+ ];
969
+ function applyBankConfig(cfg2, resolvedId) {
970
+ const section = cfg2.banks[resolvedId];
971
+ if (!section) return { cfg: cfg2, bankId: resolvedId };
972
+ const safe = { ...section };
973
+ for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
974
+ delete safe.banks;
975
+ const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
976
+ delete safe.bank;
977
+ return { cfg: { ...cfg2, ...resolvePartial(cfg2, safe) }, bankId };
978
+ }
979
+ function resolvePartial(cfg2, patch) {
980
+ const full = resolveConfig(patch);
981
+ const out = {};
982
+ for (const key of Object.keys(patch)) {
983
+ if (key in full)
984
+ out[key] = full[key];
984
985
  }
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 {
986
+ return out;
987
+ }
988
+
989
+ // src/core/git.ts
990
+ import { execFileSync as execFileSync2 } from "child_process";
991
+ import { resolve } from "path";
992
+ var US = "";
993
+ var RS = "";
994
+ function git(repo, ...args) {
995
+ return execFileSync2("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
996
+ }
997
+ function repoNameOf(repo) {
998
+ return projectNameOf(resolve(repo));
999
+ }
1000
+ function gitHeadSha(dir) {
1001
+ try {
1002
+ return git(dir, "rev-parse", "HEAD").trim() || null;
1003
+ } catch {
1004
+ return null;
1005
+ }
1006
+ }
1007
+ function commitsSince(dir, sinceSha) {
1008
+ try {
1009
+ const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
1010
+ return Number.isFinite(n) ? n : null;
1011
+ } catch {
1012
+ return null;
1013
+ }
1014
+ }
1015
+ async function retainCommit(client, repo, sha, repoName, stamp) {
1016
+ const [h, an, ae, aISO, cISO, subj, body] = git(
1017
+ repo,
1018
+ "show",
1019
+ "-s",
1020
+ `--format=%H${US}%an${US}%ae${US}%aI${US}%cI${US}%s${US}%b`,
1021
+ sha
1022
+ ).split(US);
1023
+ const msg = (subj + (body?.trim() ? "\n\n" + body.trim() : "")).trim();
1024
+ const diff = git(repo, "show", "--format=", sha);
1025
+ const content = `REF-ID: git:${sha.slice(0, 12)}
1026
+ Git commit ${sha.slice(0, 12)} in the ${repoName} repository (${an}, ${aISO}).
1027
+
1028
+ Message:
1029
+ ${msg}
1030
+
1031
+ Diff:
1032
+ ${diff}`;
1033
+ await client.retain(
1034
+ content,
1035
+ `git commit in ${repoName}`,
1036
+ `git:${sha}`,
1037
+ [.../* @__PURE__ */ new Set([...stamp?.tags ?? [], "source:git"])],
1038
+ "git",
1039
+ {
1040
+ timestamp: aISO,
1041
+ // the memory's timestamp is the commit's author date
1042
+ metadata: {
1043
+ ...stamp?.metadata,
1044
+ source: "git",
1045
+ repo: repoName,
1046
+ commit: h,
1047
+ short_sha: sha.slice(0, 12),
1048
+ author: an,
1049
+ author_email: ae,
1050
+ authored_at: aISO,
1051
+ committed_at: cISO,
1052
+ subject: subj
1008
1053
  }
1009
- pageId ||= `initiative-${this.slugify(args.title)}`;
1010
1054
  }
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"
1055
+ );
1056
+ }
1057
+ function gitLogText(repo, limit) {
1058
+ let raw;
1059
+ try {
1060
+ raw = git(
1061
+ repo,
1062
+ "log",
1063
+ `-n`,
1064
+ String(limit),
1065
+ "--no-merges",
1066
+ "--date=short",
1067
+ `--format=%h${US}%ad${US}%an${US}%s${US}%b${RS}`
1020
1068
  );
1021
- return { page_id: pageId };
1069
+ } catch {
1070
+ return "";
1022
1071
  }
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()
1072
+ return raw.split(RS).map((rec) => rec.trim()).filter(Boolean).map((rec) => {
1073
+ const [sha, date, author, subj, body] = rec.split(US);
1074
+ const header = `${sha} ${date} ${author}`;
1075
+ const msg = subj + (body?.trim() ? "\n\n" + body.trim() : "");
1076
+ return `${header}
1077
+ ${msg}`;
1078
+ }).join("\n\n---\n\n");
1079
+ }
1080
+ async function ingestGitLog(client, repo, opts = { limit: 300 }) {
1081
+ const log3 = opts.log ?? (() => {
1082
+ });
1083
+ const text = gitLogText(repo, opts.limit);
1084
+ if (!text) {
1085
+ log3("[gitlog] no commits found \u2014 skipping");
1086
+ return 0;
1087
+ }
1088
+ const repoName = repoNameOf(repo);
1089
+ const n = text.split("\n\n---\n\n").length;
1090
+ log3(`[gitlog] ingesting last ${n} commit messages for ${repoName} as ONE document \u2026`);
1091
+ try {
1092
+ const head = gitHeadSha(repo);
1093
+ const stamp = opts.stampFor?.();
1094
+ const tags = [
1095
+ .../* @__PURE__ */ new Set([
1096
+ ...stamp?.tags ?? [],
1097
+ "source:git",
1098
+ "source:git-log",
1099
+ ...head ? [`gitlog-head:${head}`] : []
1100
+ ])
1101
+ ];
1102
+ if (Object.keys(stamp?.metadata ?? {}).length) {
1103
+ await client.retain(
1104
+ text,
1105
+ `git commit-message history (last ${n}) for ${repoName}`,
1106
+ `gitlog:${repoName}`,
1107
+ tags,
1108
+ "gitlog",
1109
+ { metadata: stamp?.metadata }
1110
+ );
1111
+ } else {
1112
+ await client.retain(
1113
+ text,
1114
+ `git commit-message history (last ${n}) for ${repoName}`,
1115
+ `gitlog:${repoName}`,
1116
+ tags,
1117
+ "gitlog"
1029
1118
  );
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
1119
  }
1120
+ log3(`[gitlog] done: ${n} commit messages ingested as 1 document under strategy 'gitlog'`);
1121
+ return 0;
1122
+ } catch (e) {
1123
+ log3(` ! gitlog ingest failed: ${e.message?.slice(0, 120)}`);
1124
+ return 1;
1039
1125
  }
1040
- };
1126
+ }
1127
+
1128
+ // src/core/survey.ts
1129
+ import { spawn as realSpawn2 } from "child_process";
1130
+ import { accessSync, constants, existsSync as existsSync2 } from "fs";
1131
+ import { homedir as homedir3 } from "os";
1132
+ import { delimiter, dirname as dirname3, join as join4 } from "path";
1133
+ import { fileURLToPath as fileURLToPath2 } from "url";
1134
+ var SURVEY_DOC_IDS = [
1135
+ "repository-component-map",
1136
+ "repository-core-concepts",
1137
+ "repository-conventions-and-patterns",
1138
+ "repository-tech-stack-and-features"
1139
+ ];
1041
1140
 
1042
1141
  // src/core/status.ts
1043
1142
  import { execFileSync as execFileSync3 } from "child_process";
@@ -1066,6 +1165,8 @@ var HARNESS_NAMES = [
1066
1165
  "kilo",
1067
1166
  // Cline CLI loads dist/cline.js through its native plugin manager; file hooks cannot inject.
1068
1167
  "cline-cli",
1168
+ // Prime Agent loads dist/prime-agent.js as an extension (src/prime-agent.ts); no hook binary.
1169
+ "prime-agent",
1069
1170
  "claude-code",
1070
1171
  "cursor-cli",
1071
1172
  "codex",
@@ -1085,8 +1186,8 @@ var HOOK_BINS = {
1085
1186
  // more hook harnesses: add a HookSpec entry point (see src/cursor-hook.ts) + a registration here.
1086
1187
  };
1087
1188
  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";
1189
+ if (name === "opencode" || name === "kilo" || name === "cline-cli" || name === "prime-agent") {
1190
+ const entry = name === "opencode" ? "src/index.ts" : name === "kilo" ? "src/kilo.ts" : name === "cline-cli" ? "src/cline.ts" : "src/prime-agent.ts";
1090
1191
  return noRuntimeAdapter(
1091
1192
  name,
1092
1193
  `${name}'s runtime is built by ${entry} (the ${name} plugin entrypoint), not via the harness registry`
@@ -1150,9 +1251,55 @@ function diag(harness, event, extra = {}) {
1150
1251
  }
1151
1252
  }
1152
1253
 
1254
+ // src/core/retain-stamp.ts
1255
+ import { basename as basename2 } from "path";
1256
+ var RESERVED_TAG_PREFIX = /^(source|harness):/;
1257
+ function resolversFor(ctx) {
1258
+ return {
1259
+ // Worktree-aware like the bank id, so every linked worktree of a repo stamps the SAME name —
1260
+ // otherwise a shared bank ends up with `project:app` and `project:app-wt2` for one repository.
1261
+ gitProject: () => projectNameOf(ctx.directory),
1262
+ project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
1263
+ harness: () => ctx.harness,
1264
+ bankId: () => ctx.bankId,
1265
+ sessionId: () => ctx.sessionId ?? "unknown",
1266
+ timestamp: () => (/* @__PURE__ */ new Date()).toISOString(),
1267
+ channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
1268
+ user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
1269
+ };
1270
+ }
1271
+ function buildRetainStamp(cfg2, ctx) {
1272
+ const hasTags = Boolean(cfg2.retainTags?.length);
1273
+ const hasMetadata = Boolean(cfg2.retainMetadata && Object.keys(cfg2.retainMetadata).length);
1274
+ if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
1275
+ const base = resolversFor(ctx);
1276
+ const cache = /* @__PURE__ */ new Map();
1277
+ const resolvers = Object.fromEntries(
1278
+ Object.entries(base).map(([name, resolve2]) => [
1279
+ name,
1280
+ () => {
1281
+ const hit = cache.get(name);
1282
+ if (hit !== void 0) return hit;
1283
+ const value = resolve2();
1284
+ cache.set(name, value);
1285
+ return value;
1286
+ }
1287
+ ])
1288
+ );
1289
+ const tags = (cfg2.retainTags ?? []).map((t) => applyTemplate(t, resolvers, "retainTags").trim()).filter(Boolean).filter((t) => {
1290
+ if (!RESERVED_TAG_PREFIX.test(t)) return true;
1291
+ log.warn("retain-stamp", "ignoring reserved retainTags entry", { tag: t });
1292
+ return false;
1293
+ });
1294
+ const metadata = {};
1295
+ for (const [key, value] of Object.entries(cfg2.retainMetadata ?? {})) {
1296
+ metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
1297
+ }
1298
+ return { tags, metadata };
1299
+ }
1300
+
1153
1301
  // src/deepen.ts
1154
1302
  var DIFF_BATCH = 50;
1155
- var CONCURRENCY = 4;
1156
1303
  var LOCK_STALE_MS = 30 * 60 * 1e3;
1157
1304
  function arg(name, def) {
1158
1305
  const i = process.argv.indexOf(`--${name}`);
@@ -1226,9 +1373,16 @@ async function main() {
1226
1373
  apiUrl: API_URL,
1227
1374
  apiToken: API_TOKEN,
1228
1375
  bank: FINAL_BANK,
1376
+ maxParallelRetains: cfg.maxParallelRetains,
1229
1377
  log: log2
1230
1378
  });
1231
1379
  log2(`deepen -> ${client.apiUrl} bank=${FINAL_BANK} harness=${harness.name}`);
1380
+ const stampFor = (sessionId) => buildRetainStamp(cfg, {
1381
+ directory: REPO,
1382
+ harness: HARNESS,
1383
+ bankId: FINAL_BANK,
1384
+ sessionId
1385
+ });
1232
1386
  await client.configureBank();
1233
1387
  if (client.knowledgePagesSupported === false) {
1234
1388
  diag(harness.name, "knowledge_pages_unavailable", {
@@ -1242,7 +1396,11 @@ async function main() {
1242
1396
  const sessions = all.filter((s, i) => !chatIds.has(`chat:${s.id || `s${i}`}`));
1243
1397
  if (all.length !== sessions.length)
1244
1398
  log2(`[chat] ${all.length - sessions.length} conversations already ingested \u2014 skipping those`);
1245
- const chatFails = await ingestChats(client, sessions, { concurrency: CONCURRENCY, log: log2 });
1399
+ const chatFails = await ingestChats(client, sessions, {
1400
+ concurrency: cfg.maxParallelRetains,
1401
+ log: log2,
1402
+ stampFor
1403
+ });
1246
1404
  let gitFails = 0;
1247
1405
  if (GIT_INGEST === "none") {
1248
1406
  log2("[git] gitIngest=none \u2014 git ingestion disabled");
@@ -1252,7 +1410,7 @@ async function main() {
1252
1410
  if (gitlogCurrent) {
1253
1411
  log2("[gitlog] current with HEAD \u2014 skipping");
1254
1412
  } else {
1255
- gitFails += await ingestGitLog(client, REPO, { limit: GITLOG_LIMIT, log: log2 });
1413
+ gitFails += await ingestGitLog(client, REPO, { limit: GITLOG_LIMIT, log: log2, stampFor });
1256
1414
  }
1257
1415
  try {
1258
1416
  const canonical = `gitlog:${repoNameOf(REPO)}`;
@@ -1277,8 +1435,8 @@ async function main() {
1277
1435
  log2(`[deepen] ingesting ${shas.length} commits with full diffs (newest first) \u2026`);
1278
1436
  await pool(
1279
1437
  shas,
1280
- CONCURRENCY,
1281
- (sha) => retainCommit(client, REPO, sha, repoName),
1438
+ cfg.maxParallelRetains,
1439
+ (sha) => retainCommit(client, REPO, sha, repoName, stampFor()),
1282
1440
  () => {
1283
1441
  gitFails++;
1284
1442
  }
@@ -1304,12 +1462,19 @@ async function main() {
1304
1462
  if (behind !== null && (!best || behind < best.behind)) best = { id, sha, behind };
1305
1463
  }
1306
1464
  if (best) {
1465
+ const stamp = stampFor();
1466
+ const content = `\u2705 Codebase survey completed \u2014 baseline commit ${best.sha.slice(0, 12)}. (Internal marker: no memories are extracted from this document.)`;
1467
+ const tags = [.../* @__PURE__ */ new Set([...stamp.tags, "source:survey-baseline", "survey-state:done"])];
1307
1468
  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.)`,
1469
+ content,
1309
1470
  "hindsight codebase-survey baseline",
1310
1471
  best.id,
1311
- ["source:survey-baseline", "survey-state:done"],
1312
- "survey"
1472
+ tags,
1473
+ "survey",
1474
+ {
1475
+ // `retain` only sets metadata when it is truthy, so an empty stamp sends none.
1476
+ metadata: Object.keys(stamp.metadata).length ? stamp.metadata : void 0
1477
+ }
1313
1478
  );
1314
1479
  log2(`[survey] marker ${best.id} flipped to completed`);
1315
1480
  }