@vectorize-io/hindsight-coding-agents 0.1.1 → 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.
@@ -416,8 +416,22 @@ var CODING_BANK_TEMPLATE = {
416
416
 
417
417
  // src/core/util.ts
418
418
  var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
419
+ function semverGte(version, min) {
420
+ const parts = (v) => {
421
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
422
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
423
+ };
424
+ const a = version ? parts(version) : void 0;
425
+ const b = parts(min);
426
+ if (!a || !b) return false;
427
+ for (let i = 0; i < 3; i++) {
428
+ if (a[i] !== b[i]) return a[i] > b[i];
429
+ }
430
+ return true;
431
+ }
419
432
 
420
433
  // src/core/hindsight.ts
434
+ var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
421
435
  var KnowledgePagesUnavailableError = class extends Error {
422
436
  code = "knowledge_pages_unavailable";
423
437
  constructor() {
@@ -434,6 +448,8 @@ var HindsightClient = class {
434
448
  // async operation ids collected by retain(), for drain()
435
449
  /** Tri-state capability probe: unknown until the first page request, then cached. */
436
450
  knowledgePagesSupported;
451
+ /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
452
+ idempotentRetain;
437
453
  log;
438
454
  constructor(o) {
439
455
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
@@ -462,7 +478,8 @@ var HindsightClient = class {
462
478
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
463
479
  return r;
464
480
  }
465
- /** Retain one memory. Async by default: enqueue extraction server-side and collect its op-id for drain(). */
481
+ /** Retain one memory. ALWAYS async: enqueue extraction server-side and collect its op-id for
482
+ * drain(). Nothing in this plugin can afford to block a coding agent's hook on extraction. */
466
483
  async retain(content, context, documentId, tags, strategy, opts = {}) {
467
484
  const item = {
468
485
  content,
@@ -473,14 +490,36 @@ var HindsightClient = class {
473
490
  };
474
491
  if (opts.timestamp) item.timestamp = opts.timestamp;
475
492
  if (opts.metadata) item.metadata = opts.metadata;
476
- const isAsync = opts.async !== false;
477
- const r = await this.req("POST", this.bankUrl("/memories"), { items: [item], async: isAsync });
478
- if (isAsync) {
479
- try {
480
- const j = await r.json();
481
- if (j.operation_id) this.opIds.push(j.operation_id);
482
- } catch {
483
- }
493
+ if (opts.updateMode) item.update_mode = opts.updateMode;
494
+ const body = { items: [item], async: true };
495
+ if (opts.operationId) body.operation_id = opts.operationId;
496
+ const r = await this.req("POST", this.bankUrl("/memories"), body);
497
+ try {
498
+ const j = await r.json();
499
+ if (j.operation_id) this.opIds.push(j.operation_id);
500
+ } catch {
501
+ }
502
+ }
503
+ /**
504
+ * Whether this server honours `operation_id` on an async retain, and can therefore be appended to
505
+ * safely (see MIN_IDEMPOTENT_RETAIN_VERSION). Probed once per client via GET /version; anything
506
+ * unreachable, unparseable or older answers "no", which costs efficiency, never correctness.
507
+ */
508
+ async supportsIdempotentRetain() {
509
+ if (this.idempotentRetain === void 0) {
510
+ this.idempotentRetain = await this.probeIdempotentRetain();
511
+ this.log(`server retain idempotency: ${this.idempotentRetain ? "supported" : "unavailable"}`);
512
+ }
513
+ return this.idempotentRetain;
514
+ }
515
+ async probeIdempotentRetain() {
516
+ try {
517
+ const r = await this.req("GET", `${this.apiUrl}/version`);
518
+ if (!r.ok) return false;
519
+ const j = await r.json();
520
+ return semverGte(j.api_version, MIN_IDEMPOTENT_RETAIN_VERSION);
521
+ } catch {
522
+ return false;
484
523
  }
485
524
  }
486
525
  /**
@@ -768,8 +807,7 @@ var HindsightClient = class {
768
807
  "initiative marker",
769
808
  markerId,
770
809
  ["knowledge:feature-work", `relatedPageId:${pageId}`],
771
- "document",
772
- { async: true }
810
+ "document"
773
811
  );
774
812
  return { page_id: pageId };
775
813
  }
@@ -796,9 +834,73 @@ var HindsightClient = class {
796
834
  import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
797
835
  import { tmpdir as tmpdir2 } from "os";
798
836
  import { dirname as dirname4, join as join5 } from "path";
837
+ function sessionCacheFile(harness, sessionId) {
838
+ return join5(tmpdir2(), `hindsight-${harness}`, `${sessionId}.json`);
839
+ }
840
+ function readSessionCache(cacheFile) {
841
+ try {
842
+ return JSON.parse(readFileSync2(cacheFile, "utf8"));
843
+ } catch {
844
+ return {};
845
+ }
846
+ }
847
+ function writeSessionCache(cacheFile, cache) {
848
+ try {
849
+ mkdirSync2(dirname4(cacheFile), { recursive: true });
850
+ writeFileSync(cacheFile, JSON.stringify(cache));
851
+ } catch {
852
+ }
853
+ }
854
+ function fileCursorStore(harness) {
855
+ return {
856
+ read: (sessionId) => readSessionCache(sessionCacheFile(harness, sessionId)).retain,
857
+ write: (sessionId, cursor) => {
858
+ const file = sessionCacheFile(harness, sessionId);
859
+ writeSessionCache(file, { ...readSessionCache(file), retain: cursor });
860
+ }
861
+ };
862
+ }
799
863
 
800
864
  // src/core/retain-hook.ts
801
- import { readFileSync as readFileSync5 } from "fs";
865
+ import { readFileSync as readFileSync4 } from "fs";
866
+
867
+ // src/core/retain-cursor.ts
868
+ import { createHash } from "crypto";
869
+ function fingerprintTurns(turns, count) {
870
+ const h = createHash("sha1").update(String(count));
871
+ for (let i = 0; i < count; i++) h.update("\n" + JSON.stringify(turns[i]));
872
+ return h.digest("hex");
873
+ }
874
+ function planRetain(turns, cursor, opts) {
875
+ if (!turns.length) return { mode: "skip" };
876
+ if (!opts.appendSupported || !cursor || cursor.dirty) return { mode: "replace" };
877
+ if (cursor.bank !== opts.bank) return { mode: "replace" };
878
+ if (cursor.turns > turns.length) return { mode: "replace" };
879
+ if (fingerprintTurns(turns, cursor.turns) !== cursor.fingerprint) return { mode: "replace" };
880
+ if (cursor.turns === turns.length) return { mode: "skip" };
881
+ return { mode: "append", fromTurn: cursor.turns };
882
+ }
883
+
884
+ // src/core/uuid.ts
885
+ import { createHash as createHash2 } from "crypto";
886
+ var HINDSIGHT_NAMESPACE = "e75686a4-e923-4326-a0d1-358f1c6c3eb4";
887
+ function uuidV5(name, namespace = HINDSIGHT_NAMESPACE) {
888
+ const ns = Buffer.from(namespace.replace(/-/g, ""), "hex");
889
+ if (ns.length !== 16) throw new Error(`invalid UUID namespace: ${namespace}`);
890
+ const bytes = Buffer.from(
891
+ createHash2("sha1").update(ns).update(Buffer.from(name, "utf8")).digest().subarray(0, 16)
892
+ );
893
+ bytes[6] = bytes[6] & 15 | 80;
894
+ bytes[8] = bytes[8] & 63 | 128;
895
+ const hex = bytes.toString("hex");
896
+ return [
897
+ hex.slice(0, 8),
898
+ hex.slice(8, 12),
899
+ hex.slice(12, 16),
900
+ hex.slice(16, 20),
901
+ hex.slice(20)
902
+ ].join("-");
903
+ }
802
904
 
803
905
  // src/core/chat.ts
804
906
  function withRefId(refId, turns, baseTs) {
@@ -807,17 +909,62 @@ function withRefId(refId, turns, baseTs) {
807
909
  function renderSessionJsonl(refId, turns, baseTs) {
808
910
  return withRefId(refId, turns, baseTs).map((t) => JSON.stringify(t)).join("\n");
809
911
  }
810
- async function retainLiveSession(client, sessionId, turns, startTs, harness) {
912
+ async function supportsAppend(client) {
913
+ try {
914
+ return await client.supportsIdempotentRetain();
915
+ } catch {
916
+ return false;
917
+ }
918
+ }
919
+ var writeBacks = /* @__PURE__ */ new WeakMap();
920
+ function serialize(cursors, sessionId, write2) {
921
+ const perSession = writeBacks.get(cursors) ?? /* @__PURE__ */ new Map();
922
+ writeBacks.set(cursors, perSession);
923
+ const next = (perSession.get(sessionId) ?? Promise.resolve()).then(write2, write2);
924
+ const tail = next.catch(() => {
925
+ });
926
+ perSession.set(sessionId, tail);
927
+ void tail.then(() => {
928
+ if (perSession.get(sessionId) === tail) perSession.delete(sessionId);
929
+ });
930
+ return next;
931
+ }
932
+ async function retainLiveSession(client, sessionId, turns, startTs, harness, opts = {}) {
933
+ const cursors = opts.cursors;
934
+ if (!cursors) return writeSession(client, sessionId, turns, startTs, harness);
935
+ return serialize(
936
+ cursors,
937
+ sessionId,
938
+ () => writeSession(client, sessionId, turns, startTs, harness, cursors)
939
+ );
940
+ }
941
+ async function writeSession(client, sessionId, turns, startTs, harness, cursors) {
811
942
  const refId = `conversation:${sessionId}`;
943
+ const appendSupported = Boolean(cursors) && await supportsAppend(client);
944
+ const plan = planRetain(turns, cursors?.read(sessionId), { appendSupported, bank: client.bank });
945
+ if (plan.mode === "skip") return;
946
+ const content = plan.mode === "append" ? turns.slice(plan.fromTurn).map((t) => JSON.stringify(t)).join("\n") : renderSessionJsonl(refId, turns, startTs);
947
+ const next = {
948
+ turns: turns.length,
949
+ fingerprint: fingerprintTurns(turns, turns.length),
950
+ bank: client.bank
951
+ };
952
+ cursors?.write(sessionId, { ...next, dirty: true });
812
953
  await client.retain(
813
- renderSessionJsonl(refId, turns, startTs),
954
+ content,
814
955
  "coding agent session",
815
956
  refId,
816
957
  ["source:chat", ...harness ? [`harness:${harness}`] : []],
817
958
  "conversation",
818
959
  {
819
960
  timestamp: startTs,
820
- async: true,
961
+ updateMode: plan.mode === "append" ? "append" : void 0,
962
+ // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
963
+ // the original operation instead of extracting (or appending) twice.
964
+ operationId: uuidV5(`${client.bank}
965
+ ${refId}
966
+ ${plan.mode}
967
+ ${content}`),
821
968
  metadata: {
822
969
  source: "chat",
823
970
  session_id: sessionId,
@@ -826,6 +973,7 @@ async function retainLiveSession(client, sessionId, turns, startTs, harness) {
826
973
  }
827
974
  }
828
975
  );
976
+ cursors?.write(sessionId, next);
829
977
  }
830
978
 
831
979
  // src/core/daemon.ts
@@ -944,8 +1092,66 @@ function preflightDaemon(cfg, harness) {
944
1092
  return true;
945
1093
  }
946
1094
 
947
- // src/core/transcript.ts
948
- import { readFileSync as readFileSync4 } from "fs";
1095
+ // src/core/jsonl.ts
1096
+ import { closeSync, openSync, readSync, statSync } from "fs";
1097
+ import { StringDecoder } from "string_decoder";
1098
+ var CHUNK_BYTES = 64 * 1024;
1099
+ var MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024;
1100
+ function readJsonlTail(path, opts) {
1101
+ const maxBytes = opts.maxBytes ?? MAX_TRANSCRIPT_BYTES;
1102
+ let size;
1103
+ try {
1104
+ size = statSync(path).size;
1105
+ } catch {
1106
+ return { lines: emptyLines(), skippedBytes: 0 };
1107
+ }
1108
+ const skippedBytes = size > maxBytes ? size - maxBytes : 0;
1109
+ if (skippedBytes > 0) {
1110
+ log.warn(opts.scope, "transcript too large \u2014 retaining the most recent portion only", {
1111
+ path,
1112
+ sizeBytes: size,
1113
+ skippedBytes
1114
+ });
1115
+ }
1116
+ return { lines: streamLines(path, skippedBytes), skippedBytes };
1117
+ }
1118
+ function* emptyLines() {
1119
+ }
1120
+ function* streamLines(path, start) {
1121
+ let fd;
1122
+ try {
1123
+ fd = openSync(path, "r");
1124
+ } catch {
1125
+ return;
1126
+ }
1127
+ try {
1128
+ const buffer = Buffer.allocUnsafe(CHUNK_BYTES);
1129
+ const decoder = new StringDecoder("utf8");
1130
+ let pending = "";
1131
+ let position = start > 0 ? start - 1 : 0;
1132
+ let dropPartial = start > 0;
1133
+ for (; ; ) {
1134
+ const bytesRead = readSync(fd, buffer, 0, buffer.length, position);
1135
+ if (bytesRead <= 0) break;
1136
+ position += bytesRead;
1137
+ pending += decoder.write(buffer.subarray(0, bytesRead));
1138
+ let newline;
1139
+ while ((newline = pending.indexOf("\n")) !== -1) {
1140
+ const line = pending.slice(0, newline);
1141
+ pending = pending.slice(newline + 1);
1142
+ if (dropPartial) {
1143
+ dropPartial = false;
1144
+ continue;
1145
+ }
1146
+ yield line;
1147
+ }
1148
+ }
1149
+ pending += decoder.end();
1150
+ if (pending && !dropPartial) yield pending;
1151
+ } finally {
1152
+ closeSync(fd);
1153
+ }
1154
+ }
949
1155
 
950
1156
  // src/core/transcript-util.ts
951
1157
  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;
@@ -1007,14 +1213,8 @@ function renderLine(content, type) {
1007
1213
  return out;
1008
1214
  }
1009
1215
  function readClaudeTranscript(path) {
1010
- let raw;
1011
- try {
1012
- raw = readFileSync4(path, "utf8");
1013
- } catch {
1014
- return [];
1015
- }
1016
1216
  const turns = [];
1017
- for (const rawLine of raw.split("\n")) {
1217
+ for (const rawLine of readJsonlTail(path, { scope: "claude-code" }).lines) {
1018
1218
  const trimmed = rawLine.trim();
1019
1219
  if (!trimmed) continue;
1020
1220
  let parsed;
@@ -1047,7 +1247,9 @@ async function buildRetain(args) {
1047
1247
  const startTs = turns[0]?.timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
1048
1248
  const t0 = Date.now();
1049
1249
  try {
1050
- await retainLiveSession(client, sessionId, turns, startTs, harness);
1250
+ await retainLiveSession(client, sessionId, turns, startTs, harness, {
1251
+ cursors: args.cursors ?? fileCursorStore(harness)
1252
+ });
1051
1253
  diag(harness, "retain_ok", { ms: Date.now() - t0, turns: turns.length, session: sessionId });
1052
1254
  } catch (e) {
1053
1255
  log.warn(harness, "session write-back failed", {
@@ -1064,7 +1266,7 @@ async function runRetainHook(spec, makeClient = (o) => new HindsightClient(o)) {
1064
1266
  if (process.env.HINDSIGHT_DISABLE_HOOKS) return;
1065
1267
  let ev = {};
1066
1268
  try {
1067
- ev = JSON.parse(readFileSync5(0, "utf8"));
1269
+ ev = JSON.parse(readFileSync4(0, "utf8"));
1068
1270
  } catch {
1069
1271
  return;
1070
1272
  }
@@ -1090,7 +1292,7 @@ async function runRetainHook(spec, makeClient = (o) => new HindsightClient(o)) {
1090
1292
  }
1091
1293
 
1092
1294
  // src/core/session-start.ts
1093
- import { readFileSync as readFileSync7 } from "fs";
1295
+ import { readFileSync as readFileSync6 } from "fs";
1094
1296
 
1095
1297
  // src/core/git.ts
1096
1298
  import { execFileSync as execFileSync3 } from "child_process";
@@ -1107,13 +1309,12 @@ import { delimiter, dirname as dirname6, join as join7 } from "path";
1107
1309
  import { fileURLToPath as fileURLToPath3 } from "url";
1108
1310
 
1109
1311
  // src/core/skill-sync.ts
1110
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync6 } from "fs";
1312
+ import { cpSync, existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
1111
1313
  import { homedir as homedir4 } from "os";
1112
1314
  import { dirname as dirname7, join as join8 } from "path";
1113
1315
  import { fileURLToPath as fileURLToPath4 } from "url";
1114
1316
 
1115
1317
  // src/core/transcript-codex.ts
1116
- import { readFileSync as readFileSync8 } from "fs";
1117
1318
  function isSyntheticUserText(text) {
1118
1319
  const s = text.trimStart();
1119
1320
  return s.startsWith("# AGENTS.md instructions for ") || s.startsWith("<environment_context>");
@@ -1122,14 +1323,8 @@ function messageText(payload) {
1122
1323
  return (payload.content || []).filter((c) => c && typeof c.text === "string").map((c) => c.text).join("\n");
1123
1324
  }
1124
1325
  function readCodexTranscript(path) {
1125
- let raw;
1126
- try {
1127
- raw = readFileSync8(path, "utf8");
1128
- } catch {
1129
- return [];
1130
- }
1131
1326
  const turns = [];
1132
- for (const rawLine of raw.split("\n")) {
1327
+ for (const rawLine of readJsonlTail(path, { scope: "codex" }).lines) {
1133
1328
  const trimmed = rawLine.trim();
1134
1329
  if (!trimmed) continue;
1135
1330
  let parsed;
@@ -1163,7 +1358,6 @@ function readCodexTranscript(path) {
1163
1358
  }
1164
1359
 
1165
1360
  // src/core/transcript-cursor.ts
1166
- import { readFileSync as readFileSync9 } from "fs";
1167
1361
  function withTimestamp(turn, timestamp) {
1168
1362
  return timestamp ? { ...turn, timestamp } : turn;
1169
1363
  }
@@ -1173,14 +1367,8 @@ function textFrom(content) {
1173
1367
  return content.filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n");
1174
1368
  }
1175
1369
  function readCursorTranscript(path) {
1176
- let raw;
1177
- try {
1178
- raw = readFileSync9(path, "utf8");
1179
- } catch {
1180
- return [];
1181
- }
1182
1370
  const turns = [];
1183
- for (const rawLine of raw.split("\n")) {
1371
+ for (const rawLine of readJsonlTail(path, { scope: "cursor-cli" }).lines) {
1184
1372
  let parsed;
1185
1373
  try {
1186
1374
  parsed = JSON.parse(rawLine);
@@ -1216,17 +1404,10 @@ function readCursorTranscript(path) {
1216
1404
  }
1217
1405
 
1218
1406
  // src/core/transcript-antigravity.ts
1219
- import { readFileSync as readFileSync10 } from "fs";
1220
1407
  function readAntigravityTranscript(path) {
1221
1408
  if (!path) return [];
1222
- let raw;
1223
- try {
1224
- raw = readFileSync10(path, "utf8");
1225
- } catch {
1226
- return [];
1227
- }
1228
1409
  const turns = [];
1229
- for (const line of raw.split("\n")) {
1410
+ for (const line of readJsonlTail(path, { scope: "antigravity-cli" }).lines) {
1230
1411
  try {
1231
1412
  const event = JSON.parse(line);
1232
1413
  const role = event.role ?? event.message?.role ?? event.type;
@@ -1247,16 +1428,9 @@ function readAntigravityTranscript(path) {
1247
1428
  }
1248
1429
 
1249
1430
  // src/core/transcript-copilot.ts
1250
- import { readFileSync as readFileSync11 } from "fs";
1251
1431
  function readCopilotTranscript(path) {
1252
- let raw;
1253
- try {
1254
- raw = readFileSync11(path, "utf8");
1255
- } catch {
1256
- return [];
1257
- }
1258
1432
  const turns = [];
1259
- for (const rawLine of raw.split("\n")) {
1433
+ for (const rawLine of readJsonlTail(path, { scope: "copilot-cli" }).lines) {
1260
1434
  try {
1261
1435
  const event = JSON.parse(rawLine);
1262
1436
  const role = event.type === "user.message" ? "user" : event.type === "assistant.message" ? "assistant" : void 0;
@@ -1270,7 +1444,7 @@ function readCopilotTranscript(path) {
1270
1444
  }
1271
1445
 
1272
1446
  // src/core/transcript-grok.ts
1273
- import { existsSync as existsSync4, readFileSync as readFileSync12, readdirSync } from "fs";
1447
+ import { existsSync as existsSync4, readFileSync as readFileSync7, readdirSync } from "fs";
1274
1448
  import { homedir as homedir5 } from "os";
1275
1449
  import { join as join9 } from "path";
1276
1450
  var CHAT_HISTORY = "chat_history.jsonl";
@@ -1281,7 +1455,7 @@ function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME ||
1281
1455
  try {
1282
1456
  for (const candidate of readdirSync(sessionsDir)) {
1283
1457
  const directory = join9(sessionsDir, candidate);
1284
- if (readFileSync12(join9(directory, ".cwd"), "utf8").trim() === cwd) {
1458
+ if (readFileSync7(join9(directory, ".cwd"), "utf8").trim() === cwd) {
1285
1459
  return join9(directory, sessionId, CHAT_HISTORY);
1286
1460
  }
1287
1461
  }
@@ -1290,14 +1464,8 @@ function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME ||
1290
1464
  return direct;
1291
1465
  }
1292
1466
  function readGrokTranscript(path) {
1293
- let raw;
1294
- try {
1295
- raw = readFileSync12(path, "utf8");
1296
- } catch {
1297
- return [];
1298
- }
1299
1467
  const turns = [];
1300
- for (const rawLine of raw.split("\n")) {
1468
+ for (const rawLine of readJsonlTail(path, { scope: "grok-build" }).lines) {
1301
1469
  try {
1302
1470
  const event = JSON.parse(rawLine);
1303
1471
  if (event.type !== "user" && event.type !== "assistant") continue;
package/dist/deepen.js CHANGED
@@ -73,8 +73,27 @@ function deriveBankId(config, directory, harness = "coding") {
73
73
  });
74
74
  }
75
75
 
76
+ // src/core/retain-cursor.ts
77
+ import { createHash } from "crypto";
78
+
79
+ // src/core/uuid.ts
80
+ import { createHash as createHash2 } from "crypto";
81
+
76
82
  // src/core/util.ts
77
83
  var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
84
+ function semverGte(version, min) {
85
+ const parts = (v) => {
86
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
87
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
88
+ };
89
+ const a = version ? parts(version) : void 0;
90
+ const b = parts(min);
91
+ if (!a || !b) return false;
92
+ for (let i = 0; i < 3; i++) {
93
+ if (a[i] !== b[i]) return a[i] > b[i];
94
+ }
95
+ return true;
96
+ }
78
97
  async function pool(items, n, fn, onError, onProgress) {
79
98
  let i = 0, done = 0;
80
99
  async function worker() {
@@ -420,8 +439,7 @@ async function ingestGitLog(client, repo, opts = { limit: 300 }) {
420
439
  `git commit-message history (last ${n}) for ${repoName}`,
421
440
  `gitlog:${repoName}`,
422
441
  ["source:git", "source:git-log", ...head ? [`gitlog-head:${head}`] : []],
423
- "gitlog",
424
- { async: true }
442
+ "gitlog"
425
443
  );
426
444
  log3(`[gitlog] done: ${n} commit messages ingested as 1 document under strategy 'gitlog'`);
427
445
  return 0;
@@ -567,6 +585,7 @@ var CODING_BANK_TEMPLATE = {
567
585
  };
568
586
 
569
587
  // src/core/hindsight.ts
588
+ var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
570
589
  var KnowledgePagesUnavailableError = class extends Error {
571
590
  code = "knowledge_pages_unavailable";
572
591
  constructor() {
@@ -583,6 +602,8 @@ var HindsightClient = class {
583
602
  // async operation ids collected by retain(), for drain()
584
603
  /** Tri-state capability probe: unknown until the first page request, then cached. */
585
604
  knowledgePagesSupported;
605
+ /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
606
+ idempotentRetain;
586
607
  log;
587
608
  constructor(o) {
588
609
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
@@ -611,7 +632,8 @@ var HindsightClient = class {
611
632
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
612
633
  return r;
613
634
  }
614
- /** Retain one memory. Async by default: enqueue extraction server-side and collect its op-id for drain(). */
635
+ /** Retain one memory. ALWAYS async: enqueue extraction server-side and collect its op-id for
636
+ * drain(). Nothing in this plugin can afford to block a coding agent's hook on extraction. */
615
637
  async retain(content, context, documentId, tags, strategy, opts = {}) {
616
638
  const item = {
617
639
  content,
@@ -622,14 +644,36 @@ var HindsightClient = class {
622
644
  };
623
645
  if (opts.timestamp) item.timestamp = opts.timestamp;
624
646
  if (opts.metadata) item.metadata = opts.metadata;
625
- const isAsync = opts.async !== false;
626
- const r = await this.req("POST", this.bankUrl("/memories"), { items: [item], async: isAsync });
627
- if (isAsync) {
628
- try {
629
- const j = await r.json();
630
- if (j.operation_id) this.opIds.push(j.operation_id);
631
- } catch {
632
- }
647
+ if (opts.updateMode) item.update_mode = opts.updateMode;
648
+ const body = { items: [item], async: true };
649
+ if (opts.operationId) body.operation_id = opts.operationId;
650
+ const r = await this.req("POST", this.bankUrl("/memories"), body);
651
+ try {
652
+ const j = await r.json();
653
+ if (j.operation_id) this.opIds.push(j.operation_id);
654
+ } catch {
655
+ }
656
+ }
657
+ /**
658
+ * Whether this server honours `operation_id` on an async retain, and can therefore be appended to
659
+ * safely (see MIN_IDEMPOTENT_RETAIN_VERSION). Probed once per client via GET /version; anything
660
+ * unreachable, unparseable or older answers "no", which costs efficiency, never correctness.
661
+ */
662
+ async supportsIdempotentRetain() {
663
+ if (this.idempotentRetain === void 0) {
664
+ this.idempotentRetain = await this.probeIdempotentRetain();
665
+ this.log(`server retain idempotency: ${this.idempotentRetain ? "supported" : "unavailable"}`);
666
+ }
667
+ return this.idempotentRetain;
668
+ }
669
+ async probeIdempotentRetain() {
670
+ try {
671
+ const r = await this.req("GET", `${this.apiUrl}/version`);
672
+ if (!r.ok) return false;
673
+ const j = await r.json();
674
+ return semverGte(j.api_version, MIN_IDEMPOTENT_RETAIN_VERSION);
675
+ } catch {
676
+ return false;
633
677
  }
634
678
  }
635
679
  /**
@@ -917,8 +961,7 @@ var HindsightClient = class {
917
961
  "initiative marker",
918
962
  markerId,
919
963
  ["knowledge:feature-work", `relatedPageId:${pageId}`],
920
- "document",
921
- { async: true }
964
+ "document"
922
965
  );
923
966
  return { page_id: pageId };
924
967
  }
@@ -1211,8 +1254,7 @@ async function main() {
1211
1254
  "hindsight codebase-survey baseline",
1212
1255
  best.id,
1213
1256
  ["source:survey-baseline", "survey-state:done"],
1214
- "survey",
1215
- { async: true }
1257
+ "survey"
1216
1258
  );
1217
1259
  log2(`[survey] marker ${best.id} flipped to completed`);
1218
1260
  }