@vectorize-io/hindsight-coding-agents 0.1.0 → 0.1.2

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.
@@ -238,7 +238,9 @@ function readEnvConfig(env = process.env) {
238
238
  function loadConfig(opts = {}) {
239
239
  const o = typeof opts === "string" ? { path: opts } : opts;
240
240
  const withEnv = applyLayer({}, readEnvConfig(), o.harness);
241
- return resolveConfig(applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness));
241
+ const raw = applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness);
242
+ if (!raw.harness && o.harness) raw.harness = o.harness;
243
+ return resolveConfig(raw);
242
244
  }
243
245
  var BANK_OVERRIDE_EXCLUDED = [
244
246
  "bankId",
@@ -322,7 +324,7 @@ var GITLOG_MISSION = "You are ingesting an aggregated block of git commit MESSAG
322
324
  var CONVERSATION_MISSION = `You are ingesting a developer conversation as a JSONL transcript (one {role, content} turn per line): the user's requests, the assistant's narration, and compact 'action' turns naming each tool use and its target (e.g. "Edit boltons/strutils.py") with no arguments or outputs. It may be a SHORT decision chat or a LONG working session \u2014 scale the facts to the substance, never to the message count. Extract the FEWEST facts that capture the OUTCOME: the settled DECISIONS and their exact rules/values (quote literals VERBATIM); concrete CHANGES to specific code entities; problems and how they were resolved; conventions or invariants established; at most one fact for a notable REJECTED alternative ('initially proposed X, changed to Y because Z'). A short decision chat usually yields 1-2 facts; a substantial working session several. CRITICAL: a conversation REVISES itself \u2014 record ONLY the FINAL state as what is in effect; a superseded proposal appears ONLY inside the rejected fact, NEVER as its own 'decided' fact; if the same setting changes several times keep only the LAST, and make unmistakably clear which choice WON. Do NOT emit one fact per message, per intermediate proposal, or per action turn. Keep issue/PR references (#123, GH-123) VERBATIM and emit each as an ENTITY. Preserve the 'REF-ID: <token>' marker verbatim in every fact. Do not invent; capture only what was actually settled.`;
323
325
  var REFLECT_MISSION = "You are a debugging assistant with the project's past decisions in memory (git rationale and developer chats). Given a bug's SYMPTOM, find the past decision whose rationale explains the ROOT CAUSE \u2014 not one that merely shares vocabulary. Answer with the PRECISE fix: state the EXACT rule and the LITERAL values, identifiers, strings, numbers, or set members that were decided \u2014 quote them VERBATIM, never paraphrase, generalize, or omit them (give the actual decided value, not 'the project standard'). If memories CONFLICT on the same rule, the LATEST decision wins \u2014 prefer facts that explicitly amend or supersede an earlier one, state the superseded rule as no longer in effect, and never present it as the fix. Name the function/file to change and cite the REF-ID(s). If NOTHING in memory genuinely explains THIS symptom, say exactly that in one short sentence \u2014 a wrong-but-confident nearest match is worse than an honest miss; never stretch an unrelated decision to fit.";
324
326
  var DOCUMENT_MISSION = "You are ingesting a standalone document (notes, docs, or structural findings). Extract the concrete facts, concepts, and structure it describes.";
325
- var OBSERVATIONS_MISSION = "Consolidate durable knowledge about THIS codebase \u2014 recurring patterns, conventions, module responsibilities, and how components relate \u2014 from the ingested commits and conversations. Favor stable structural understanding over one-off details.";
327
+ var OBSERVATIONS_MISSION = "Consolidate durable knowledge about THIS codebase \u2014 recurring patterns, conventions, module responsibilities, and how components relate \u2014 from the ingested commits and conversations. Favor stable structural understanding over one-off details. When a new fact contradicts or supersedes an existing observation, UPDATE that observation to reflect the current state rather than creating a sibling alongside it; note that the rule was revised and when, so the superseded version is visible as history rather than as a competing claim.";
326
328
  var RETAIN_STRATEGIES = {
327
329
  git: { retain_mission: GIT_MISSION, retain_extraction_mode: "verbose" },
328
330
  // ONE big aggregated document (last N commit messages, no diffs) -> a larger chunk size so it stays
@@ -440,8 +442,22 @@ var CODING_BANK_TEMPLATE = {
440
442
 
441
443
  // src/core/util.ts
442
444
  var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
445
+ function semverGte(version, min) {
446
+ const parts = (v) => {
447
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
448
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
449
+ };
450
+ const a = version ? parts(version) : void 0;
451
+ const b = parts(min);
452
+ if (!a || !b) return false;
453
+ for (let i = 0; i < 3; i++) {
454
+ if (a[i] !== b[i]) return a[i] > b[i];
455
+ }
456
+ return true;
457
+ }
443
458
 
444
459
  // src/core/hindsight.ts
460
+ var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
445
461
  var KnowledgePagesUnavailableError = class extends Error {
446
462
  code = "knowledge_pages_unavailable";
447
463
  constructor() {
@@ -458,6 +474,8 @@ var HindsightClient = class {
458
474
  // async operation ids collected by retain(), for drain()
459
475
  /** Tri-state capability probe: unknown until the first page request, then cached. */
460
476
  knowledgePagesSupported;
477
+ /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
478
+ idempotentRetain;
461
479
  log;
462
480
  constructor(o) {
463
481
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
@@ -486,7 +504,8 @@ var HindsightClient = class {
486
504
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
487
505
  return r;
488
506
  }
489
- /** Retain one memory. Async by default: enqueue extraction server-side and collect its op-id for drain(). */
507
+ /** Retain one memory. ALWAYS async: enqueue extraction server-side and collect its op-id for
508
+ * drain(). Nothing in this plugin can afford to block a coding agent's hook on extraction. */
490
509
  async retain(content, context, documentId, tags, strategy, opts = {}) {
491
510
  const item = {
492
511
  content,
@@ -497,14 +516,36 @@ var HindsightClient = class {
497
516
  };
498
517
  if (opts.timestamp) item.timestamp = opts.timestamp;
499
518
  if (opts.metadata) item.metadata = opts.metadata;
500
- const isAsync = opts.async !== false;
501
- const r = await this.req("POST", this.bankUrl("/memories"), { items: [item], async: isAsync });
502
- if (isAsync) {
503
- try {
504
- const j = await r.json();
505
- if (j.operation_id) this.opIds.push(j.operation_id);
506
- } catch {
507
- }
519
+ if (opts.updateMode) item.update_mode = opts.updateMode;
520
+ const body = { items: [item], async: true };
521
+ if (opts.operationId) body.operation_id = opts.operationId;
522
+ const r = await this.req("POST", this.bankUrl("/memories"), body);
523
+ try {
524
+ const j = await r.json();
525
+ if (j.operation_id) this.opIds.push(j.operation_id);
526
+ } catch {
527
+ }
528
+ }
529
+ /**
530
+ * Whether this server honours `operation_id` on an async retain, and can therefore be appended to
531
+ * safely (see MIN_IDEMPOTENT_RETAIN_VERSION). Probed once per client via GET /version; anything
532
+ * unreachable, unparseable or older answers "no", which costs efficiency, never correctness.
533
+ */
534
+ async supportsIdempotentRetain() {
535
+ if (this.idempotentRetain === void 0) {
536
+ this.idempotentRetain = await this.probeIdempotentRetain();
537
+ this.log(`server retain idempotency: ${this.idempotentRetain ? "supported" : "unavailable"}`);
538
+ }
539
+ return this.idempotentRetain;
540
+ }
541
+ async probeIdempotentRetain() {
542
+ try {
543
+ const r = await this.req("GET", `${this.apiUrl}/version`);
544
+ if (!r.ok) return false;
545
+ const j = await r.json();
546
+ return semverGte(j.api_version, MIN_IDEMPOTENT_RETAIN_VERSION);
547
+ } catch {
548
+ return false;
508
549
  }
509
550
  }
510
551
  /**
@@ -792,8 +833,7 @@ var HindsightClient = class {
792
833
  "initiative marker",
793
834
  markerId,
794
835
  ["knowledge:feature-work", `relatedPageId:${pageId}`],
795
- "document",
796
- { async: true }
836
+ "document"
797
837
  );
798
838
  return { page_id: pageId };
799
839
  }
@@ -882,7 +922,13 @@ function writeSessionCache(cacheFile, cache) {
882
922
  }
883
923
 
884
924
  // src/core/retain-hook.ts
885
- import { readFileSync as readFileSync5 } from "fs";
925
+ import { readFileSync as readFileSync4 } from "fs";
926
+
927
+ // src/core/retain-cursor.ts
928
+ import { createHash } from "crypto";
929
+
930
+ // src/core/uuid.ts
931
+ import { createHash as createHash2 } from "crypto";
886
932
 
887
933
  // src/core/daemon.ts
888
934
  import { execFileSync as execFileSync2, spawn as realSpawn2 } from "child_process";
@@ -1000,8 +1046,66 @@ function preflightDaemon(cfg, harness) {
1000
1046
  return true;
1001
1047
  }
1002
1048
 
1003
- // src/core/transcript.ts
1004
- import { readFileSync as readFileSync4 } from "fs";
1049
+ // src/core/jsonl.ts
1050
+ import { closeSync, openSync, readSync, statSync } from "fs";
1051
+ import { StringDecoder } from "string_decoder";
1052
+ var CHUNK_BYTES = 64 * 1024;
1053
+ var MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024;
1054
+ function readJsonlTail(path, opts) {
1055
+ const maxBytes = opts.maxBytes ?? MAX_TRANSCRIPT_BYTES;
1056
+ let size;
1057
+ try {
1058
+ size = statSync(path).size;
1059
+ } catch {
1060
+ return { lines: emptyLines(), skippedBytes: 0 };
1061
+ }
1062
+ const skippedBytes = size > maxBytes ? size - maxBytes : 0;
1063
+ if (skippedBytes > 0) {
1064
+ log.warn(opts.scope, "transcript too large \u2014 retaining the most recent portion only", {
1065
+ path,
1066
+ sizeBytes: size,
1067
+ skippedBytes
1068
+ });
1069
+ }
1070
+ return { lines: streamLines(path, skippedBytes), skippedBytes };
1071
+ }
1072
+ function* emptyLines() {
1073
+ }
1074
+ function* streamLines(path, start) {
1075
+ let fd;
1076
+ try {
1077
+ fd = openSync(path, "r");
1078
+ } catch {
1079
+ return;
1080
+ }
1081
+ try {
1082
+ const buffer = Buffer.allocUnsafe(CHUNK_BYTES);
1083
+ const decoder = new StringDecoder("utf8");
1084
+ let pending = "";
1085
+ let position = start > 0 ? start - 1 : 0;
1086
+ let dropPartial = start > 0;
1087
+ for (; ; ) {
1088
+ const bytesRead = readSync(fd, buffer, 0, buffer.length, position);
1089
+ if (bytesRead <= 0) break;
1090
+ position += bytesRead;
1091
+ pending += decoder.write(buffer.subarray(0, bytesRead));
1092
+ let newline;
1093
+ while ((newline = pending.indexOf("\n")) !== -1) {
1094
+ const line = pending.slice(0, newline);
1095
+ pending = pending.slice(newline + 1);
1096
+ if (dropPartial) {
1097
+ dropPartial = false;
1098
+ continue;
1099
+ }
1100
+ yield line;
1101
+ }
1102
+ }
1103
+ pending += decoder.end();
1104
+ if (pending && !dropPartial) yield pending;
1105
+ } finally {
1106
+ closeSync(fd);
1107
+ }
1108
+ }
1005
1109
 
1006
1110
  // src/core/transcript-util.ts
1007
1111
  var MEMORY_TAG_RE = /<(hook_prompt|hindsight_memory|hindsight_memories|hindsight_bank|relevant_memories|user_feedback|hindsight_knowledge|hindsight_knowledge_refresh)\b[\s\S]*?<\/\1>/g;
@@ -1039,7 +1143,7 @@ function actionLine(tool, input) {
1039
1143
  }
1040
1144
 
1041
1145
  // src/core/session-start.ts
1042
- import { readFileSync as readFileSync7 } from "fs";
1146
+ import { readFileSync as readFileSync6 } from "fs";
1043
1147
 
1044
1148
  // src/core/git.ts
1045
1149
  import { execFileSync as execFileSync3 } from "child_process";
@@ -1264,7 +1368,7 @@ function startCodebaseSurvey(repoDir, opts = {}) {
1264
1368
  var DEEPEN_DIFF_TARGET = 300;
1265
1369
 
1266
1370
  // src/core/skill-sync.ts
1267
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync6 } from "fs";
1371
+ import { cpSync, existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
1268
1372
  import { homedir as homedir4 } from "os";
1269
1373
  import { dirname as dirname7, join as join8 } from "path";
1270
1374
  import { fileURLToPath as fileURLToPath4 } from "url";
@@ -1288,7 +1392,7 @@ function syncCompanionSkill(harness, opts = {}) {
1288
1392
  const dst = join8(opts.home ?? homedir4(), ...parts, "hindsight-coding-agent");
1289
1393
  const dstMd = join8(dst, "SKILL.md");
1290
1394
  if (!existsSync3(dstMd)) return;
1291
- if (readFileSync6(srcMd, "utf8") !== readFileSync6(dstMd, "utf8")) {
1395
+ if (readFileSync5(srcMd, "utf8") !== readFileSync5(dstMd, "utf8")) {
1292
1396
  cpSync(src, dst, { recursive: true });
1293
1397
  }
1294
1398
  } catch {
@@ -1344,8 +1448,7 @@ async function buildSessionStartContext(args) {
1344
1448
  "hindsight codebase-survey baseline",
1345
1449
  `${SURVEY_BASELINE_PREFIX}${sha}`,
1346
1450
  [SURVEY_BASELINE_TAG],
1347
- "survey",
1348
- { async: true }
1451
+ "survey"
1349
1452
  )
1350
1453
  ).catch(() => {
1351
1454
  });
@@ -1365,7 +1468,7 @@ async function buildSessionStartContext(args) {
1365
1468
  cold = docIds !== void 0 ? docIds.size === 0 : void 0;
1366
1469
  gitDocIds = docIds;
1367
1470
  if (docIds !== void 0) {
1368
- startSeed(cwd, { limit: cfg.seedLimit });
1471
+ startSeed(cwd, { limit: cfg.seedLimit, harness });
1369
1472
  if (docIds.size === 0) {
1370
1473
  if (cfg.codebaseSurvey !== false) {
1371
1474
  startSurvey(cwd, {
@@ -1442,7 +1545,7 @@ async function runSessionStartHook(spec, makeClient = (o) => new HindsightClient
1442
1545
  try {
1443
1546
  let ev = {};
1444
1547
  try {
1445
- ev = JSON.parse(readFileSync7(0, "utf8"));
1548
+ ev = JSON.parse(readFileSync6(0, "utf8"));
1446
1549
  } catch {
1447
1550
  return;
1448
1551
  }
@@ -1472,7 +1575,6 @@ async function runSessionStartHook(spec, makeClient = (o) => new HindsightClient
1472
1575
  }
1473
1576
 
1474
1577
  // src/core/transcript-codex.ts
1475
- import { readFileSync as readFileSync8 } from "fs";
1476
1578
  function isSyntheticUserText(text) {
1477
1579
  const s = text.trimStart();
1478
1580
  return s.startsWith("# AGENTS.md instructions for ") || s.startsWith("<environment_context>");
@@ -1481,14 +1583,8 @@ function messageText(payload) {
1481
1583
  return (payload.content || []).filter((c) => c && typeof c.text === "string").map((c) => c.text).join("\n");
1482
1584
  }
1483
1585
  function readCodexTranscript(path) {
1484
- let raw;
1485
- try {
1486
- raw = readFileSync8(path, "utf8");
1487
- } catch {
1488
- return [];
1489
- }
1490
1586
  const turns = [];
1491
- for (const rawLine of raw.split("\n")) {
1587
+ for (const rawLine of readJsonlTail(path, { scope: "codex" }).lines) {
1492
1588
  const trimmed = rawLine.trim();
1493
1589
  if (!trimmed) continue;
1494
1590
  let parsed;
@@ -1522,7 +1618,6 @@ function readCodexTranscript(path) {
1522
1618
  }
1523
1619
 
1524
1620
  // src/core/transcript-cursor.ts
1525
- import { readFileSync as readFileSync9 } from "fs";
1526
1621
  function withTimestamp(turn, timestamp) {
1527
1622
  return timestamp ? { ...turn, timestamp } : turn;
1528
1623
  }
@@ -1532,14 +1627,8 @@ function textFrom(content) {
1532
1627
  return content.filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n");
1533
1628
  }
1534
1629
  function readCursorTranscript(path) {
1535
- let raw;
1536
- try {
1537
- raw = readFileSync9(path, "utf8");
1538
- } catch {
1539
- return [];
1540
- }
1541
1630
  const turns = [];
1542
- for (const rawLine of raw.split("\n")) {
1631
+ for (const rawLine of readJsonlTail(path, { scope: "cursor-cli" }).lines) {
1543
1632
  let parsed;
1544
1633
  try {
1545
1634
  parsed = JSON.parse(rawLine);
@@ -1575,17 +1664,10 @@ function readCursorTranscript(path) {
1575
1664
  }
1576
1665
 
1577
1666
  // src/core/transcript-antigravity.ts
1578
- import { readFileSync as readFileSync10 } from "fs";
1579
1667
  function readAntigravityTranscript(path) {
1580
1668
  if (!path) return [];
1581
- let raw;
1582
- try {
1583
- raw = readFileSync10(path, "utf8");
1584
- } catch {
1585
- return [];
1586
- }
1587
1669
  const turns = [];
1588
- for (const line of raw.split("\n")) {
1670
+ for (const line of readJsonlTail(path, { scope: "antigravity-cli" }).lines) {
1589
1671
  try {
1590
1672
  const event = JSON.parse(line);
1591
1673
  const role = event.role ?? event.message?.role ?? event.type;
@@ -1606,16 +1688,9 @@ function readAntigravityTranscript(path) {
1606
1688
  }
1607
1689
 
1608
1690
  // src/core/transcript-copilot.ts
1609
- import { readFileSync as readFileSync11 } from "fs";
1610
1691
  function readCopilotTranscript(path) {
1611
- let raw;
1612
- try {
1613
- raw = readFileSync11(path, "utf8");
1614
- } catch {
1615
- return [];
1616
- }
1617
1692
  const turns = [];
1618
- for (const rawLine of raw.split("\n")) {
1693
+ for (const rawLine of readJsonlTail(path, { scope: "copilot-cli" }).lines) {
1619
1694
  try {
1620
1695
  const event = JSON.parse(rawLine);
1621
1696
  const role = event.type === "user.message" ? "user" : event.type === "assistant.message" ? "assistant" : void 0;
@@ -1629,7 +1704,7 @@ function readCopilotTranscript(path) {
1629
1704
  }
1630
1705
 
1631
1706
  // src/core/transcript-grok.ts
1632
- import { existsSync as existsSync4, readFileSync as readFileSync12, readdirSync } from "fs";
1707
+ import { existsSync as existsSync4, readFileSync as readFileSync7, readdirSync } from "fs";
1633
1708
  import { homedir as homedir5 } from "os";
1634
1709
  import { join as join9 } from "path";
1635
1710
  var CHAT_HISTORY = "chat_history.jsonl";
@@ -1640,7 +1715,7 @@ function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME ||
1640
1715
  try {
1641
1716
  for (const candidate of readdirSync(sessionsDir)) {
1642
1717
  const directory = join9(sessionsDir, candidate);
1643
- if (readFileSync12(join9(directory, ".cwd"), "utf8").trim() === cwd) {
1718
+ if (readFileSync7(join9(directory, ".cwd"), "utf8").trim() === cwd) {
1644
1719
  return join9(directory, sessionId, CHAT_HISTORY);
1645
1720
  }
1646
1721
  }
@@ -1649,14 +1724,8 @@ function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME ||
1649
1724
  return direct;
1650
1725
  }
1651
1726
  function readGrokTranscript(path) {
1652
- let raw;
1653
- try {
1654
- raw = readFileSync12(path, "utf8");
1655
- } catch {
1656
- return [];
1657
- }
1658
1727
  const turns = [];
1659
- for (const rawLine of raw.split("\n")) {
1728
+ for (const rawLine of readJsonlTail(path, { scope: "grok-build" }).lines) {
1660
1729
  try {
1661
1730
  const event = JSON.parse(rawLine);
1662
1731
  if (event.type !== "user" && event.type !== "assistant") continue;