@vectorize-io/hindsight-coding-agents 0.3.3 → 0.4.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
@@ -44,8 +44,8 @@ function getProjectRootFromGit(directory) {
44
44
  return null;
45
45
  }
46
46
  }
47
- function projectNameOf(directory) {
48
- return gitProjectName(directory, true);
47
+ function projectNameOf(directory, sessionRoot) {
48
+ return gitProjectName(directory, true, sessionRoot);
49
49
  }
50
50
  var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
51
51
  function nearestExistingDir(directory) {
@@ -61,18 +61,24 @@ function nearestExistingDir(directory) {
61
61
  function dirName(directory) {
62
62
  return directory && basename(directory) || "unknown";
63
63
  }
64
- function gitProjectName(directory, resolveWorktrees) {
64
+ function mainWorktreeRoot(directory, sessionRoot = "") {
65
+ const candidates = [
66
+ nearestExistingDir(directory),
67
+ sessionRoot,
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 root;
73
+ }
74
+ return null;
75
+ }
76
+ function gitProjectName(directory, resolveWorktrees, sessionRoot = "") {
65
77
  if (resolveWorktrees) {
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
- }
78
+ const root = mainWorktreeRoot(directory, sessionRoot);
79
+ if (root) return basename(root);
74
80
  }
75
- return dirName(directory);
81
+ return dirName(sessionRoot || directory);
76
82
  }
77
83
  function configuredDir(dir) {
78
84
  const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
@@ -92,23 +98,38 @@ function mapLookup(map, directory) {
92
98
  }
93
99
  return best?.bank;
94
100
  }
101
+ function lookupDirectories(config, directory, sessionRoot = "") {
102
+ const directories = [normalize(directory)];
103
+ if (config.resolveWorktrees ?? true) {
104
+ const root = mainWorktreeRoot(directory, sessionRoot);
105
+ const normalizedRoot = root ? normalize(root) : "";
106
+ if (normalizedRoot && normalizedRoot !== directories[0]) directories.push(normalizedRoot);
107
+ }
108
+ return directories;
109
+ }
95
110
  function isOptedIn(config, directory) {
96
111
  if (!config.optInOnly) return true;
97
112
  if (!directory) return false;
98
- const cwd = normalize(directory);
99
- if ((config.optInPaths ?? []).some((dir) => dir && isWithin(cwd, configuredDir(dir))))
113
+ const directories = lookupDirectories(config, directory);
114
+ if (directories.some(
115
+ (candidate) => (config.optInPaths ?? []).some(
116
+ (configured) => configured && isWithin(candidate, configuredDir(configured))
117
+ )
118
+ ))
100
119
  return true;
101
- return Boolean(config.mapPathToBank && mapLookup(config.mapPathToBank, directory));
120
+ const pathMap = config.mapPathToBank;
121
+ return Boolean(pathMap && directories.some((candidate) => mapLookup(pathMap, candidate)));
102
122
  }
103
- function deriveBankId(config, directory, harness = "coding") {
104
- const mapped = directory && config.mapPathToBank ? mapLookup(config.mapPathToBank, directory) : void 0;
123
+ function deriveBankId(config, directory, harness = "coding", sessionRoot) {
124
+ const pathMap = config.mapPathToBank;
125
+ const mapped = directory && pathMap ? lookupDirectories(config, directory, sessionRoot).map((candidate) => mapLookup(pathMap, candidate)).find((bank) => bank !== void 0) : void 0;
105
126
  if (mapped) return mapped;
106
127
  const dynamic = config.dynamicBankId ?? !config.bankId;
107
128
  if (!dynamic) return config.bankId || DEFAULT_BANK_NAME;
108
129
  const resolvers = {
109
130
  harness: () => harness,
110
131
  project: () => dirName(directory),
111
- gitProject: () => gitProjectName(directory, config.resolveWorktrees ?? true),
132
+ gitProject: () => gitProjectName(directory, config.resolveWorktrees ?? true, sessionRoot),
112
133
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
113
134
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
114
135
  };
@@ -190,7 +211,10 @@ var KNOWLEDGE_LABELS = {
190
211
  }
191
212
  ]
192
213
  };
193
- var PAGES = [
214
+ function pageScopeRule(project) {
215
+ return ` Scope this page to ${project} ITSELF: the bank also holds facts about external tools, libraries and services that ${project} merely uses, configures, deploys or discusses, and those belong to somebody else's codebase. Include something only when its subject is ${project}'s own code, configuration or process; when it is about a dependency, leave it out however well-evidenced it looks \u2014 including any commit SHA or identifier that belongs to that dependency's repository rather than this one.`;
216
+ }
217
+ var PAGE_TAXONOMY = [
194
218
  {
195
219
  name: "Component map",
196
220
  source_query: "From this project's commit history and past discussions, what are the main components/modules/subsystems, what is each responsible for, and how do they relate to or depend on one another? Describe the structure and responsibilities.",
@@ -217,11 +241,23 @@ var PAGES = [
217
241
  tags: ["knowledge:feature-work"]
218
242
  }
219
243
  ];
244
+ function pagesFor(project) {
245
+ const scope = pageScopeRule(project);
246
+ return PAGE_TAXONOMY.map((page) => ({ ...page, source_query: page.source_query + scope }));
247
+ }
220
248
  var PAGE_MAX_TOKENS = 4096;
221
- var PAGE_TRIGGER = {
222
- fact_types: ["world", "experience", "observation"],
223
- refresh_after_consolidation: true
224
- };
249
+ var PAGE_FACT_TYPES = ["world", "experience", "observation"];
250
+ function buildPageTrigger(cfg2 = {}) {
251
+ const base = { fact_types: PAGE_FACT_TYPES };
252
+ switch (cfg2.pageTriggerType) {
253
+ case "cron":
254
+ return { ...base, refresh_cron: cfg2.pageTriggerCron };
255
+ case "manual":
256
+ return { ...base, refresh_after_consolidation: false };
257
+ default:
258
+ return { ...base, refresh_after_consolidation: true };
259
+ }
260
+ }
225
261
  var CODING_BANK_TEMPLATE = {
226
262
  version: "1",
227
263
  bank: {
@@ -276,6 +312,7 @@ async function pool(items, n, fn, onError, onProgress) {
276
312
  }
277
313
 
278
314
  // src/core/hindsight.ts
315
+ var DEFAULT_OBSERVATION_SCOPES = "shared";
279
316
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
280
317
  var RateLimitedError = class extends Error {
281
318
  constructor(retryAfterMs2) {
@@ -308,8 +345,12 @@ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
308
345
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
309
346
  var HindsightClient = class {
310
347
  apiUrl;
311
- apiToken;
348
+ /** The credential the NEXT request will sign with — NOT the one the config file holds. The two
349
+ * diverge exactly when #3600 bites, which is why `hindsight_diagnose` reports both. */
350
+ token;
351
+ tokenProvider;
312
352
  bank;
353
+ project;
313
354
  opIds = [];
314
355
  // async operation ids collected by retain(), for drain()
315
356
  /** Tri-state capability probe: unknown until the first page request, then cached. */
@@ -318,34 +359,81 @@ var HindsightClient = class {
318
359
  idempotentRetain;
319
360
  log;
320
361
  maxParallelRetains;
362
+ observationScopes;
321
363
  constructor(o) {
322
364
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
323
- this.apiToken = o.apiToken;
365
+ this.token = o.apiToken;
366
+ this.tokenProvider = o.tokenProvider;
324
367
  this.bank = o.bank;
368
+ this.project = o.project;
325
369
  this.log = o.log ?? (() => {
326
370
  });
327
371
  this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
372
+ this.observationScopes = o.observationScopes ?? DEFAULT_OBSERVATION_SCOPES;
373
+ }
374
+ /** The credential in use, for diagnostics. Never log or report the VALUE — booleans only. */
375
+ get apiToken() {
376
+ return this.token;
328
377
  }
329
378
  headers() {
330
379
  const h = { "Content-Type": "application/json" };
331
- if (this.apiToken) h["Authorization"] = `Bearer ${this.apiToken}`;
380
+ if (this.token) h["Authorization"] = `Bearer ${this.token}`;
332
381
  return h;
333
382
  }
383
+ /** Re-read the credential from the live config. Returns whether it actually CHANGED — a retry is
384
+ * only worth sending if it did, so a genuinely wrong key still surfaces as one 401 rather than
385
+ * doubling every failing request. */
386
+ refreshToken() {
387
+ if (!this.tokenProvider) return false;
388
+ let next;
389
+ try {
390
+ next = this.tokenProvider();
391
+ } catch {
392
+ return false;
393
+ }
394
+ if (next === this.token) return false;
395
+ this.token = next;
396
+ return true;
397
+ }
398
+ /**
399
+ * The ONE place a request is signed. Every fetch goes through it — the generic `req`, the drain
400
+ * poll and `reflect` — because a 401 recovery wired into only one of them leaves the others
401
+ * failing forever, which is how #3600 read from the outside: hooks worked, in-session tools did
402
+ * not.
403
+ *
404
+ * On a 401 the credential is re-resolved and the request replayed ONCE (its body is already a
405
+ * string, so replay is exact). A 401 means the server did nothing, so replaying is side-effect
406
+ * free even for retain. The retry shares the caller's `signal`, deliberately: one deadline still
407
+ * bounds the whole call.
408
+ */
409
+ async fetchWithAuth(url, init) {
410
+ const send = () => fetch(url, { ...init, headers: this.headers() });
411
+ const r = await send();
412
+ if (r.status !== 401 || !this.refreshToken()) return r;
413
+ return send();
414
+ }
415
+ /** A 401 with no `Authorization` header is a different failure from a rejected key, and the
416
+ * server answers identically for both — only the client knows which it sent. */
417
+ authHint(status) {
418
+ if (status !== 401) return "";
419
+ return this.token ? " (the configured apiToken was rejected \u2014 check ~/.hindsight/coding-agent.json)" : " (no apiToken is configured, so no Authorization header was sent)";
420
+ }
334
421
  bankUrl(suffix = "") {
335
422
  return `${this.apiUrl}/v1/default/banks/${encodeURIComponent(this.bank)}${suffix}`;
336
423
  }
337
424
  /** `tolerate` adds statuses that are returned to the caller instead of thrown (404 always is). */
338
425
  async req(method, url, body, tolerate = []) {
339
- const r = await fetch(url, {
426
+ const r = await this.fetchWithAuth(url, {
340
427
  method,
341
- headers: this.headers(),
342
428
  body: body ? JSON.stringify(body) : void 0,
343
429
  signal: AbortSignal.timeout(15e3)
344
430
  });
345
431
  if (r.status === 429 && !tolerate.includes(429))
346
432
  throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
347
433
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
348
- throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
434
+ throw new Error(
435
+ `${method} ${url} -> ${r.status} ${await r.text()}${this.authHint(r.status)}`
436
+ );
349
437
  return r;
350
438
  }
351
439
  /** Retain one memory. ALWAYS async: enqueue extraction server-side and collect its op-id for
@@ -356,7 +444,11 @@ var HindsightClient = class {
356
444
  context,
357
445
  document_id: documentId,
358
446
  tags,
359
- strategy
447
+ strategy,
448
+ // Sent on EVERY retain, including the server default `combined`, so the scoping a bank's
449
+ // observations were built under is a property of the write rather than of whichever server
450
+ // version happened to process it. Servers older than 0.4.15 ignore the field.
451
+ observation_scopes: this.observationScopes
360
452
  };
361
453
  if (opts.timestamp) item.timestamp = opts.timestamp;
362
454
  if (opts.metadata) item.metadata = opts.metadata;
@@ -435,7 +527,7 @@ var HindsightClient = class {
435
527
  this.log(
436
528
  seeded ? `[bank] structure applied to ${this.bank}: entity_labels {knowledge}, strategies {git, gitlog, conversation, document} \u2014 missions left as configured` : `[bank] template applied to ${this.bank}: missions, entity_labels {knowledge}, strategies {git, gitlog, conversation, document}`
437
529
  );
438
- await this.seedPages();
530
+ await this.seedPages(opts.pageTrigger);
439
531
  }
440
532
  /**
441
533
  * Whether this bank already carries bank-level mission overrides — ours from an earlier seed, or
@@ -493,7 +585,7 @@ var HindsightClient = class {
493
585
  let backoffMs = POLL_CYCLE_MS;
494
586
  await pool([...pending], this.maxParallelRetains, async (id) => {
495
587
  try {
496
- const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
588
+ const r = await this.fetchWithAuth(this.bankUrl(`/operations/${id}`), { method: "GET" });
497
589
  if (r.status === 429) {
498
590
  backoffMs = Math.min(
499
591
  RETRY_AFTER_CEILING_MS,
@@ -519,18 +611,23 @@ var HindsightClient = class {
519
611
  `[wait] ${label} drained \u2014 ${ids.length - pending.size} done, ${failed} failed` + (pending.size ? `, ${pending.size} still pending at timeout` : "")
520
612
  );
521
613
  }
522
- /** Reflect: synthesized, root-cause answer over the bank. Bounded so a slow server never hangs a caller. */
523
- async reflect(query, opts = {}) {
614
+ /**
615
+ * Reflect: synthesized, root-cause answer over the bank. Bounded so a slow server never hangs a
616
+ * caller — but `timeoutMs` is REQUIRED, deliberately: the right deadline differs by an order of
617
+ * magnitude between the automatic hook (25s, to fit the host's window) and the agent-invoked
618
+ * tool (minutes, on a populated bank). This used to default to 120s, which silently overrode the
619
+ * tool's configured window and aborted every high-budget synthesis mid-flight (#3590).
620
+ */
621
+ async reflect(query, opts) {
524
622
  const ctrl = new AbortController();
525
- const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 12e4);
623
+ const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs);
526
624
  try {
527
- const resp = await fetch(this.bankUrl("/reflect"), {
625
+ const resp = await this.fetchWithAuth(this.bankUrl("/reflect"), {
528
626
  method: "POST",
529
- headers: this.headers(),
530
627
  body: JSON.stringify({ query, budget: opts.budget ?? "high" }),
531
628
  signal: ctrl.signal
532
629
  });
533
- if (!resp.ok) throw new Error(`reflect ${resp.status}`);
630
+ if (!resp.ok) throw new Error(`reflect ${resp.status}${this.authHint(resp.status)}`);
534
631
  const data = await resp.json();
535
632
  return (data.text || "").trim();
536
633
  } finally {
@@ -614,16 +711,18 @@ var HindsightClient = class {
614
711
  }));
615
712
  }
616
713
  /**
617
- * Seed the fixed `PAGES` taxonomy as knowledge-base pages at the tree root, idempotently.
714
+ * Seed the fixed page taxonomy as knowledge-base pages at the tree root, idempotently.
618
715
  *
619
716
  * Matched by NAME, not id: `/knowledge-base/pages` mints its own `kp-…` id, so a stable
620
717
  * client-chosen id isn't available to match on (unlike the old mental-model path, which keyed
621
718
  * off a slug). Names are unique per folder server-side, which makes them a sound key.
622
719
  *
623
720
  * An existing page is PATCHed rather than recreated so a plugin upgrade that rewords a
624
- * `source_query` re-syncs onto the live page instead of orphaning its synthesized content.
721
+ * `source_query` re-syncs onto the live page instead of orphaning its synthesized content —
722
+ * which is how `pageScopeRule`'s repo name reaches banks seeded by an earlier version.
625
723
  */
626
- async seedPages() {
724
+ async seedPages(pageTrigger = buildPageTrigger()) {
725
+ const pages = pagesFor(this.project ?? this.bank);
627
726
  const existing = /* @__PURE__ */ new Map();
628
727
  let roots;
629
728
  try {
@@ -640,14 +739,14 @@ var HindsightClient = class {
640
739
  }
641
740
  let created = 0;
642
741
  let updated = 0;
643
- for (const page of PAGES) {
742
+ for (const page of pages) {
644
743
  const hit = existing.get(page.name.toLowerCase());
645
744
  const body = {
646
745
  name: page.name,
647
746
  source_query: page.source_query,
648
747
  tags: page.tags,
649
748
  max_tokens: PAGE_MAX_TOKENS,
650
- trigger: PAGE_TRIGGER
749
+ trigger: pageTrigger
651
750
  };
652
751
  if (!hit) {
653
752
  const r = await this.req("POST", this.bankUrl("/knowledge-base/pages"), body, [409]);
@@ -676,7 +775,7 @@ var HindsightClient = class {
676
775
  }
677
776
  }
678
777
  this.log(
679
- `[bank] knowledge pages seeded on ${this.bank}: ${created} created, ${updated} re-synced, ${PAGES.length - created - updated} unchanged`
778
+ `[bank] knowledge pages seeded on ${this.bank}: ${created} created, ${updated} re-synced, ${pages.length - created - updated} unchanged`
680
779
  );
681
780
  }
682
781
  /** URL/id-safe slug: lowercase, non-alphanumerics → "-", trim dashes, cap length; fallback "initiative". */
@@ -686,7 +785,8 @@ var HindsightClient = class {
686
785
  /**
687
786
  * Active-path capture: register a major feature as a per-initiative page + a tagged marker memory.
688
787
  * 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.
788
+ * Update (relatesToPageId) → no new page; only a marker accruing to the existing page, so an
789
+ * enhancement or a mid-work plan change lands on the initiative it belongs to.
690
790
  */
691
791
  async captureInitiative(args) {
692
792
  let pageId = args.relatesToPageId;
@@ -697,10 +797,7 @@ var HindsightClient = class {
697
797
  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
798
  parent_id: folderId,
699
799
  tags: ["knowledge:feature-work"],
700
- trigger: {
701
- fact_types: ["world", "experience", "observation"],
702
- refresh_after_consolidation: true
703
- }
800
+ trigger: args.pageTrigger ?? buildPageTrigger()
704
801
  });
705
802
  try {
706
803
  const j = await r.json();
@@ -709,7 +806,7 @@ var HindsightClient = class {
709
806
  }
710
807
  pageId ||= `initiative-${this.slugify(args.title)}`;
711
808
  }
712
- const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
809
+ const verb = args.relatesToPageId ? "Update to an existing initiative" : "New initiative";
713
810
  const content = `${verb}: ${args.title}. ${args.summary}`;
714
811
  const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
715
812
  const tags = [
@@ -813,7 +910,7 @@ async function ingestChats(client, sessions, opts = {}) {
813
910
  // src/core/config.ts
814
911
  import { readFileSync } from "fs";
815
912
  import { homedir as homedir2 } from "os";
816
- import { join as join3 } from "path";
913
+ import { join as join4 } from "path";
817
914
 
818
915
  // src/core/seed.ts
819
916
  import { spawn as realSpawn } from "child_process";
@@ -821,11 +918,89 @@ import { dirname as dirname2, join as join2 } from "path";
821
918
  import { fileURLToPath } from "url";
822
919
  var DEFAULT_SEED_LIMIT = 300;
823
920
 
921
+ // src/core/log.ts
922
+ import { appendFileSync, mkdirSync } from "fs";
923
+ import { tmpdir } from "os";
924
+ import { dirname as dirname3, join as join3 } from "path";
925
+ var WEIGHT = { debug: 10, info: 20, warn: 30, error: 40 };
926
+ var current = ["debug", "info", "warn", "error"].find(
927
+ (l) => l === process.env.HINDSIGHT_LOG_LEVEL
928
+ ) ?? "info";
929
+ function setLogLevel(level) {
930
+ if (!process.env.HINDSIGHT_LOG_LEVEL) current = level;
931
+ }
932
+ function logFilePath() {
933
+ return process.env.HINDSIGHT_LOG_FILE || join3(tmpdir(), "hindsight-coding-agent", "plugin.log");
934
+ }
935
+ function write(level, scope, msg, extra) {
936
+ if (WEIGHT[level] < WEIGHT[current]) return;
937
+ try {
938
+ const file = logFilePath();
939
+ mkdirSync(dirname3(file), { recursive: true });
940
+ appendFileSync(
941
+ file,
942
+ `${(/* @__PURE__ */ new Date()).toISOString()} ${level.toUpperCase().padEnd(5)} [${scope}] ${msg}` + (extra && Object.keys(extra).length ? ` ${JSON.stringify(extra)}` : "") + "\n"
943
+ );
944
+ } catch {
945
+ }
946
+ }
947
+ var log = {
948
+ debug: (scope, msg, extra) => write("debug", scope, msg, extra),
949
+ info: (scope, msg, extra) => write("info", scope, msg, extra),
950
+ warn: (scope, msg, extra) => write("warn", scope, msg, extra),
951
+ error: (scope, msg, extra) => write("error", scope, msg, extra)
952
+ };
953
+ function describeError(value, maxChars = 200) {
954
+ const parts = [];
955
+ const seen = /* @__PURE__ */ new Set();
956
+ let current2 = value;
957
+ while (current2 && !seen.has(current2)) {
958
+ seen.add(current2);
959
+ const error = current2;
960
+ const text = typeof error.message === "string" ? error.message : String(current2);
961
+ const withCode = error.code ? `${text} (${String(error.code)})` : text;
962
+ if (withCode && parts.at(-1) !== withCode) parts.push(withCode);
963
+ current2 = error.cause;
964
+ }
965
+ return (parts.join(": ") || String(value)).slice(0, maxChars);
966
+ }
967
+
824
968
  // src/core/config.ts
825
- var CONFIG_PATH = process.env.HINDSIGHT_CONFIG || join3(homedir2(), ".hindsight", "coding-agent.json");
969
+ var CONFIG_PATH = process.env.HINDSIGHT_CONFIG || join4(homedir2(), ".hindsight", "coding-agent.json");
826
970
  var DEFAULT_DAEMON_PORT = 9077;
827
- var DEFAULT_DAEMON_IDLE_TIMEOUT = 300;
828
971
  var DEFAULT_DAEMON_PROFILE = "coding-agent";
972
+ function resolvePageTriggerType(raw) {
973
+ if (raw.pageTriggerType === "manual") return "manual";
974
+ if (raw.pageTriggerType === "cron") {
975
+ if (raw.pageTriggerCron?.trim()) return "cron";
976
+ log.warn(
977
+ "config",
978
+ 'pageTriggerType "cron" needs pageTriggerCron (UTC 5-field, e.g. "0 3 * * *") \u2014 falling back to "auto-refresh"'
979
+ );
980
+ }
981
+ return "auto-refresh";
982
+ }
983
+ var DEFAULT_REFLECT_TOOL_TIMEOUT_MS = 33e4;
984
+ var REFLECT_BUDGETS = ["low", "mid", "high"];
985
+ function resolveReflectBudget(raw) {
986
+ const value = raw.reflectBudget;
987
+ if (value === void 0) return "high";
988
+ if (typeof value === "string" && REFLECT_BUDGETS.includes(value))
989
+ return value;
990
+ log.warn("config", `ignoring reflectBudget=${JSON.stringify(value)} \u2014 expected low|mid|high`);
991
+ return "high";
992
+ }
993
+ var OBSERVATION_SCOPE_MODES = ["shared", "combined", "per_tag", "all_combinations"];
994
+ function resolveObservationScopes(raw) {
995
+ const value = raw;
996
+ if (typeof value === "string")
997
+ return OBSERVATION_SCOPE_MODES.includes(value) ? value : DEFAULT_OBSERVATION_SCOPES;
998
+ if (Array.isArray(value)) {
999
+ const scopes = value.filter((scope) => Array.isArray(scope)).map((scope) => scope.filter((t) => typeof t === "string" && t.trim() !== ""));
1000
+ if (scopes.length) return scopes;
1001
+ }
1002
+ return DEFAULT_OBSERVATION_SCOPES;
1003
+ }
829
1004
  function resolveConfig(raw = {}) {
830
1005
  const serverMode = ["cloud", "self-hosted", "daemon"].includes(raw.serverMode) ? raw.serverMode : "cloud";
831
1006
  const apiPort = raw.apiPort || DEFAULT_DAEMON_PORT;
@@ -837,7 +1012,7 @@ function resolveConfig(raw = {}) {
837
1012
  apiUrl: serverMode === "daemon" ? `http://127.0.0.1:${apiPort}` : raw.apiUrl ?? "https://api.hindsight.vectorize.io",
838
1013
  apiToken: raw.apiToken || void 0,
839
1014
  apiPort,
840
- daemonIdleTimeout: raw.daemonIdleTimeout ?? DEFAULT_DAEMON_IDLE_TIMEOUT,
1015
+ daemonIdleTimeout: raw.daemonIdleTimeout,
841
1016
  daemonProfile: raw.daemonProfile || DEFAULT_DAEMON_PROFILE,
842
1017
  embedVersion: raw.embedVersion || void 0,
843
1018
  embedPackagePath: raw.embedPackagePath || void 0,
@@ -852,11 +1027,18 @@ function resolveConfig(raw = {}) {
852
1027
  harness: raw.harness ?? "opencode",
853
1028
  disabled: raw.disabled ?? false,
854
1029
  retainSessions: raw.retainSessions ?? true,
855
- // opencode: write back by default (parity with hook-harness Stop)
1030
+ // write sessions back by default, every harness
856
1031
  maxParallelRetains: raw.maxParallelRetains || 10,
857
1032
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
1033
+ // Inherit an explicitly-raised reflectTimeoutMs (that is what users reaching for a longer
1034
+ // reflect already set), but never let it LOWER the tool below the default — a short window is
1035
+ // set to bound the automatic hook, not to cut off a call the agent is waiting on.
1036
+ reflectToolTimeoutMs: raw.reflectToolTimeoutMs || Math.max(raw.reflectTimeoutMs || 0, DEFAULT_REFLECT_TOOL_TIMEOUT_MS),
1037
+ reflectBudget: resolveReflectBudget(raw),
858
1038
  autoReflect: raw.autoReflect ?? true,
859
1039
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
1040
+ pageTriggerType: resolvePageTriggerType(raw),
1041
+ pageTriggerCron: raw.pageTriggerCron?.trim() || void 0,
860
1042
  autoSeed: raw.autoSeed ?? true,
861
1043
  seedLimit: raw.seedLimit || DEFAULT_SEED_LIMIT,
862
1044
  codebaseSurvey: raw.codebaseSurvey ?? true,
@@ -870,6 +1052,7 @@ function resolveConfig(raw = {}) {
870
1052
  retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
871
1053
  Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
872
1054
  ) : {},
1055
+ observationScopes: resolveObservationScopes(raw.observationScopes),
873
1056
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
874
1057
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
875
1058
  };
@@ -916,8 +1099,12 @@ var ENV_KEYS = {
916
1099
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
917
1100
  maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
918
1101
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
1102
+ reflectToolTimeoutMs: "HINDSIGHT_REFLECT_TOOL_TIMEOUT_MS",
1103
+ reflectBudget: "HINDSIGHT_REFLECT_BUDGET",
919
1104
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
920
1105
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
1106
+ pageTriggerType: "HINDSIGHT_PAGE_TRIGGER_TYPE",
1107
+ pageTriggerCron: "HINDSIGHT_PAGE_TRIGGER_CRON",
921
1108
  autoSeed: "HINDSIGHT_AUTO_SEED",
922
1109
  seedLimit: "HINDSIGHT_SEED_LIMIT",
923
1110
  codebaseSurvey: "HINDSIGHT_CODEBASE_SURVEY",
@@ -926,6 +1113,9 @@ var ENV_KEYS = {
926
1113
  surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
927
1114
  logLevel: "HINDSIGHT_LOG_LEVEL",
928
1115
  gitIngest: "HINDSIGHT_GIT_INGEST",
1116
+ // Scalar modes only ("shared", "combined", "per_tag", "all_combinations"). An explicit scope
1117
+ // list is a list OF lists, which does not survive flattening into one variable — file-only.
1118
+ observationScopes: "HINDSIGHT_OBSERVATION_SCOPES",
929
1119
  // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
930
1120
  // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
931
1121
  retainTags: "HINDSIGHT_RETAIN_TAGS"
@@ -946,6 +1136,7 @@ var ENV_NUMBERS = /* @__PURE__ */ new Set([
946
1136
  "daemonIdleTimeout",
947
1137
  "maxParallelRetains",
948
1138
  "reflectTimeoutMs",
1139
+ "reflectToolTimeoutMs",
949
1140
  "pageRefreshEveryTurns",
950
1141
  "seedLimit",
951
1142
  "surveyBudgetUsd",
@@ -1103,6 +1294,13 @@ function gitLogText(repo, limit) {
1103
1294
  ${msg}`;
1104
1295
  }).join("\n\n---\n\n");
1105
1296
  }
1297
+ function gitLogNewestAuthorDate(repo) {
1298
+ try {
1299
+ return git(repo, "log", "-n", "1", "--no-merges", "--format=%aI").trim() || null;
1300
+ } catch {
1301
+ return null;
1302
+ }
1303
+ }
1106
1304
  async function ingestGitLog(client, repo, opts = { limit: 300 }) {
1107
1305
  const log3 = opts.log ?? (() => {
1108
1306
  });
@@ -1125,24 +1323,22 @@ async function ingestGitLog(client, repo, opts = { limit: 300 }) {
1125
1323
  ...head ? [`gitlog-head:${head}`] : []
1126
1324
  ])
1127
1325
  ];
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"
1144
- );
1145
- }
1326
+ await client.retain(
1327
+ text,
1328
+ `git commit-message history (last ${n}) for ${repoName}`,
1329
+ `gitlog:${repoName}`,
1330
+ tags,
1331
+ "gitlog",
1332
+ {
1333
+ // Anchor the document in time on the newest commit it contains, so extraction can date the
1334
+ // facts it pulls out of these messages. Previously no timestamp was passed at all: retain
1335
+ // then stamped "now", the extraction prompt got `Event Date: Unknown`, and every fact landed
1336
+ // with a null occurred_start/occurred_end — invisible to temporal search (#3602).
1337
+ timestamp: gitLogNewestAuthorDate(repo) ?? void 0,
1338
+ // `retain` only sets metadata when it is truthy, so an empty stamp sends none.
1339
+ metadata: Object.keys(stamp?.metadata ?? {}).length ? stamp?.metadata : void 0
1340
+ }
1341
+ );
1146
1342
  log3(`[gitlog] done: ${n} commit messages ingested as 1 document under strategy 'gitlog'`);
1147
1343
  return 0;
1148
1344
  } catch (e) {
@@ -1155,7 +1351,7 @@ async function ingestGitLog(client, repo, opts = { limit: 300 }) {
1155
1351
  import { spawn as realSpawn2 } from "child_process";
1156
1352
  import { accessSync, constants, existsSync as existsSync2 } from "fs";
1157
1353
  import { homedir as homedir3 } from "os";
1158
- import { delimiter, dirname as dirname3, join as join4 } from "path";
1354
+ import { delimiter, dirname as dirname4, join as join5 } from "path";
1159
1355
  import { fileURLToPath as fileURLToPath2 } from "url";
1160
1356
  var SURVEY_DOC_IDS = [
1161
1357
  "repository-component-map",
@@ -1191,6 +1387,9 @@ var HARNESS_NAMES = [
1191
1387
  "kilo",
1192
1388
  // Cline CLI loads dist/cline.js through its native plugin manager; file hooks cannot inject.
1193
1389
  "cline-cli",
1390
+ // DeepSeek Harness loads dist/dsh.js as a native Cordis plugin (src/dsh.ts). Its Claude Code /
1391
+ // Codex hook bridges are optional packages, so there is no hook binary to install either.
1392
+ "dsh",
1194
1393
  // Prime Agent loads dist/prime-agent.js as an extension (src/prime-agent.ts); no hook binary.
1195
1394
  "prime-agent",
1196
1395
  "claude-code",
@@ -1211,9 +1410,16 @@ var HOOK_BINS = {
1211
1410
  "grok-build": "hindsight-grok-hook"
1212
1411
  // more hook harnesses: add a HookSpec entry point (see src/cursor-hook.ts) + a registration here.
1213
1412
  };
1413
+ var PLUGIN_ENTRYPOINTS = {
1414
+ opencode: "src/index.ts",
1415
+ kilo: "src/kilo.ts",
1416
+ "cline-cli": "src/cline.ts",
1417
+ "prime-agent": "src/prime-agent.ts",
1418
+ dsh: "src/dsh.ts"
1419
+ };
1214
1420
  async function getHarness(name) {
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";
1421
+ const entry = PLUGIN_ENTRYPOINTS[name];
1422
+ if (entry) {
1217
1423
  return noRuntimeAdapter(
1218
1424
  name,
1219
1425
  `${name}'s runtime is built by ${entry} (the ${name} plugin entrypoint), not via the harness registry`
@@ -1231,41 +1437,6 @@ async function getHarness(name) {
1231
1437
 
1232
1438
  // src/core/diag.ts
1233
1439
  import { appendFileSync as appendFileSync2 } from "fs";
1234
-
1235
- // src/core/log.ts
1236
- import { appendFileSync, mkdirSync } from "fs";
1237
- import { tmpdir } from "os";
1238
- import { dirname as dirname4, join as join5 } from "path";
1239
- var WEIGHT = { debug: 10, info: 20, warn: 30, error: 40 };
1240
- var current = ["debug", "info", "warn", "error"].find(
1241
- (l) => l === process.env.HINDSIGHT_LOG_LEVEL
1242
- ) ?? "info";
1243
- function setLogLevel(level) {
1244
- if (!process.env.HINDSIGHT_LOG_LEVEL) current = level;
1245
- }
1246
- function logFilePath() {
1247
- return process.env.HINDSIGHT_LOG_FILE || join5(tmpdir(), "hindsight-coding-agent", "plugin.log");
1248
- }
1249
- function write(level, scope, msg, extra) {
1250
- if (WEIGHT[level] < WEIGHT[current]) return;
1251
- try {
1252
- const file = logFilePath();
1253
- mkdirSync(dirname4(file), { recursive: true });
1254
- appendFileSync(
1255
- file,
1256
- `${(/* @__PURE__ */ new Date()).toISOString()} ${level.toUpperCase().padEnd(5)} [${scope}] ${msg}` + (extra && Object.keys(extra).length ? ` ${JSON.stringify(extra)}` : "") + "\n"
1257
- );
1258
- } catch {
1259
- }
1260
- }
1261
- var log = {
1262
- debug: (scope, msg, extra) => write("debug", scope, msg, extra),
1263
- info: (scope, msg, extra) => write("info", scope, msg, extra),
1264
- warn: (scope, msg, extra) => write("warn", scope, msg, extra),
1265
- error: (scope, msg, extra) => write("error", scope, msg, extra)
1266
- };
1267
-
1268
- // src/core/diag.ts
1269
1440
  function diagFilePath() {
1270
1441
  return process.env.HINDSIGHT_DIAG_FILE || "/tmp/hindsight-plugin.log";
1271
1442
  }
@@ -1287,7 +1458,7 @@ function resolversFor(ctx) {
1287
1458
  return {
1288
1459
  // Worktree-aware like the bank id, so every linked worktree of a repo stamps the SAME name —
1289
1460
  // otherwise a shared bank ends up with `project:app` and `project:app-wt2` for one repository.
1290
- gitProject: () => projectNameOf(ctx.directory),
1461
+ gitProject: () => projectNameOf(ctx.directory, ctx.sessionRoot),
1291
1462
  project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
1292
1463
  harness: () => ctx.harness,
1293
1464
  bankId: () => ctx.bankId,
@@ -1402,7 +1573,12 @@ async function main() {
1402
1573
  apiUrl: API_URL,
1403
1574
  apiToken: API_TOKEN,
1404
1575
  bank: FINAL_BANK,
1576
+ // Names the repository in every seeded page's query, so page synthesis can tell this
1577
+ // project's decisions from those of a dependency it merely discusses (#3476). Same
1578
+ // worktree-aware name the gitlog document id uses, so all worktrees agree on it.
1579
+ project: repoNameOf(REPO),
1405
1580
  maxParallelRetains: cfg.maxParallelRetains,
1581
+ observationScopes: cfg.observationScopes,
1406
1582
  log: log2
1407
1583
  });
1408
1584
  log2(`deepen -> ${client.apiUrl} bank=${FINAL_BANK} harness=${harness.name}`);
@@ -1412,7 +1588,7 @@ async function main() {
1412
1588
  bankId: FINAL_BANK,
1413
1589
  sessionId
1414
1590
  });
1415
- await client.configureBank();
1591
+ await client.configureBank({ pageTrigger: buildPageTrigger(cfg) });
1416
1592
  if (client.knowledgePagesSupported === false) {
1417
1593
  diag(harness.name, "knowledge_pages_unavailable", {
1418
1594
  bank: FINAL_BANK,
@@ -1420,11 +1596,18 @@ async function main() {
1420
1596
  });
1421
1597
  }
1422
1598
  const gitIds = await client.listDocumentIds("source:git");
1423
- const chatIds = await client.listDocumentIds("source:chat").catch(() => /* @__PURE__ */ new Set());
1424
- const all = await harness.chatReader.read({ conversations: CONV, repo: REPO });
1425
- const sessions = all.filter((s, i) => !chatIds.has(`chat:${s.id || `s${i}`}`));
1426
- if (all.length !== sessions.length)
1427
- log2(`[chat] ${all.length - sessions.length} conversations already ingested \u2014 skipping those`);
1599
+ let sessions = [];
1600
+ if (!cfg.retainSessions) {
1601
+ log2("[chat] retainSessions: false \u2014 skipping conversation import");
1602
+ } else {
1603
+ const chatIds = await client.listDocumentIds("source:chat").catch(() => /* @__PURE__ */ new Set());
1604
+ const all = await harness.chatReader.read({ conversations: CONV, repo: REPO });
1605
+ sessions = all.filter((s, i) => !chatIds.has(`chat:${s.id || `s${i}`}`));
1606
+ if (all.length !== sessions.length)
1607
+ log2(
1608
+ `[chat] ${all.length - sessions.length} conversations already ingested \u2014 skipping those`
1609
+ );
1610
+ }
1428
1611
  const chatFails = await ingestChats(client, sessions, {
1429
1612
  concurrency: cfg.maxParallelRetains,
1430
1613
  log: log2,
@@ -1543,7 +1726,7 @@ async function main() {
1543
1726
  main().catch((e) => {
1544
1727
  diag("deepen", "deepen_failed", {
1545
1728
  bank: FINAL_BANK,
1546
- error: String(e?.message || e).slice(0, 200)
1729
+ error: describeError(e)
1547
1730
  });
1548
1731
  console.error("deepen failed:", e.message || e);
1549
1732
  try {