@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.
package/dist/cline.js CHANGED
@@ -175,7 +175,9 @@ function readEnvConfig(env = process.env) {
175
175
  function loadConfig(opts = {}) {
176
176
  const o = typeof opts === "string" ? { path: opts } : opts;
177
177
  const withEnv = applyLayer({}, readEnvConfig(), o.harness);
178
- return resolveConfig(applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness));
178
+ const raw = applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness);
179
+ if (!raw.harness && o.harness) raw.harness = o.harness;
180
+ return resolveConfig(raw);
179
181
  }
180
182
  var BANK_OVERRIDE_EXCLUDED = [
181
183
  "bankId",
@@ -278,7 +280,7 @@ var GITLOG_MISSION = "You are ingesting an aggregated block of git commit MESSAG
278
280
  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.`;
279
281
  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.";
280
282
  var DOCUMENT_MISSION = "You are ingesting a standalone document (notes, docs, or structural findings). Extract the concrete facts, concepts, and structure it describes.";
281
- 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.";
283
+ 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.";
282
284
  var RETAIN_STRATEGIES = {
283
285
  git: { retain_mission: GIT_MISSION, retain_extraction_mode: "verbose" },
284
286
  // ONE big aggregated document (last N commit messages, no diffs) -> a larger chunk size so it stays
@@ -396,8 +398,22 @@ var CODING_BANK_TEMPLATE = {
396
398
 
397
399
  // src/core/util.ts
398
400
  var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
401
+ function semverGte(version2, min) {
402
+ const parts = (v) => {
403
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
404
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
405
+ };
406
+ const a = version2 ? parts(version2) : void 0;
407
+ const b = parts(min);
408
+ if (!a || !b) return false;
409
+ for (let i = 0; i < 3; i++) {
410
+ if (a[i] !== b[i]) return a[i] > b[i];
411
+ }
412
+ return true;
413
+ }
399
414
 
400
415
  // src/core/hindsight.ts
416
+ var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
401
417
  var KnowledgePagesUnavailableError = class extends Error {
402
418
  code = "knowledge_pages_unavailable";
403
419
  constructor() {
@@ -414,6 +430,8 @@ var HindsightClient = class {
414
430
  // async operation ids collected by retain(), for drain()
415
431
  /** Tri-state capability probe: unknown until the first page request, then cached. */
416
432
  knowledgePagesSupported;
433
+ /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
434
+ idempotentRetain;
417
435
  log;
418
436
  constructor(o) {
419
437
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
@@ -442,7 +460,8 @@ var HindsightClient = class {
442
460
  throw new Error(`${method} ${url2} -> ${r.status} ${await r.text()}`);
443
461
  return r;
444
462
  }
445
- /** Retain one memory. Async by default: enqueue extraction server-side and collect its op-id for drain(). */
463
+ /** Retain one memory. ALWAYS async: enqueue extraction server-side and collect its op-id for
464
+ * drain(). Nothing in this plugin can afford to block a coding agent's hook on extraction. */
446
465
  async retain(content, context, documentId, tags, strategy, opts = {}) {
447
466
  const item = {
448
467
  content,
@@ -453,14 +472,36 @@ var HindsightClient = class {
453
472
  };
454
473
  if (opts.timestamp) item.timestamp = opts.timestamp;
455
474
  if (opts.metadata) item.metadata = opts.metadata;
456
- const isAsync = opts.async !== false;
457
- const r = await this.req("POST", this.bankUrl("/memories"), { items: [item], async: isAsync });
458
- if (isAsync) {
459
- try {
460
- const j = await r.json();
461
- if (j.operation_id) this.opIds.push(j.operation_id);
462
- } catch {
463
- }
475
+ if (opts.updateMode) item.update_mode = opts.updateMode;
476
+ const body = { items: [item], async: true };
477
+ if (opts.operationId) body.operation_id = opts.operationId;
478
+ const r = await this.req("POST", this.bankUrl("/memories"), body);
479
+ try {
480
+ const j = await r.json();
481
+ if (j.operation_id) this.opIds.push(j.operation_id);
482
+ } catch {
483
+ }
484
+ }
485
+ /**
486
+ * Whether this server honours `operation_id` on an async retain, and can therefore be appended to
487
+ * safely (see MIN_IDEMPOTENT_RETAIN_VERSION). Probed once per client via GET /version; anything
488
+ * unreachable, unparseable or older answers "no", which costs efficiency, never correctness.
489
+ */
490
+ async supportsIdempotentRetain() {
491
+ if (this.idempotentRetain === void 0) {
492
+ this.idempotentRetain = await this.probeIdempotentRetain();
493
+ this.log(`server retain idempotency: ${this.idempotentRetain ? "supported" : "unavailable"}`);
494
+ }
495
+ return this.idempotentRetain;
496
+ }
497
+ async probeIdempotentRetain() {
498
+ try {
499
+ const r = await this.req("GET", `${this.apiUrl}/version`);
500
+ if (!r.ok) return false;
501
+ const j = await r.json();
502
+ return semverGte(j.api_version, MIN_IDEMPOTENT_RETAIN_VERSION);
503
+ } catch {
504
+ return false;
464
505
  }
465
506
  }
466
507
  /**
@@ -748,8 +789,7 @@ var HindsightClient = class {
748
789
  "initiative marker",
749
790
  markerId,
750
791
  ["knowledge:feature-work", `relatedPageId:${pageId}`],
751
- "document",
752
- { async: true }
792
+ "document"
753
793
  );
754
794
  return { page_id: pageId };
755
795
  }
@@ -15789,7 +15829,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15789
15829
  docId,
15790
15830
  ["source:upload", ...opts.harness ? [`harness:${opts.harness}`] : []],
15791
15831
  "document",
15792
- { async: true, metadata: opts.harness ? { harness: opts.harness } : void 0 }
15832
+ { metadata: opts.harness ? { harness: opts.harness } : void 0 }
15793
15833
  );
15794
15834
  return { ok: true, doc_id: docId };
15795
15835
  })
@@ -15797,6 +15837,51 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15797
15837
  ];
15798
15838
  }
15799
15839
 
15840
+ // src/core/retain-cursor.ts
15841
+ import { createHash } from "crypto";
15842
+ function fingerprintTurns(turns, count) {
15843
+ const h = createHash("sha1").update(String(count));
15844
+ for (let i = 0; i < count; i++) h.update("\n" + JSON.stringify(turns[i]));
15845
+ return h.digest("hex");
15846
+ }
15847
+ function planRetain(turns, cursor, opts) {
15848
+ if (!turns.length) return { mode: "skip" };
15849
+ if (!opts.appendSupported || !cursor || cursor.dirty) return { mode: "replace" };
15850
+ if (cursor.bank !== opts.bank) return { mode: "replace" };
15851
+ if (cursor.turns > turns.length) return { mode: "replace" };
15852
+ if (fingerprintTurns(turns, cursor.turns) !== cursor.fingerprint) return { mode: "replace" };
15853
+ if (cursor.turns === turns.length) return { mode: "skip" };
15854
+ return { mode: "append", fromTurn: cursor.turns };
15855
+ }
15856
+ function memoryCursorStore() {
15857
+ const cursors = /* @__PURE__ */ new Map();
15858
+ return {
15859
+ read: (sessionId2) => cursors.get(sessionId2),
15860
+ write: (sessionId2, cursor) => void cursors.set(sessionId2, cursor)
15861
+ };
15862
+ }
15863
+
15864
+ // src/core/uuid.ts
15865
+ import { createHash as createHash2 } from "crypto";
15866
+ var HINDSIGHT_NAMESPACE = "e75686a4-e923-4326-a0d1-358f1c6c3eb4";
15867
+ function uuidV5(name, namespace = HINDSIGHT_NAMESPACE) {
15868
+ const ns = Buffer.from(namespace.replace(/-/g, ""), "hex");
15869
+ if (ns.length !== 16) throw new Error(`invalid UUID namespace: ${namespace}`);
15870
+ const bytes = Buffer.from(
15871
+ createHash2("sha1").update(ns).update(Buffer.from(name, "utf8")).digest().subarray(0, 16)
15872
+ );
15873
+ bytes[6] = bytes[6] & 15 | 80;
15874
+ bytes[8] = bytes[8] & 63 | 128;
15875
+ const hex3 = bytes.toString("hex");
15876
+ return [
15877
+ hex3.slice(0, 8),
15878
+ hex3.slice(8, 12),
15879
+ hex3.slice(12, 16),
15880
+ hex3.slice(16, 20),
15881
+ hex3.slice(20)
15882
+ ].join("-");
15883
+ }
15884
+
15800
15885
  // src/core/chat.ts
15801
15886
  function withRefId(refId, turns, baseTs) {
15802
15887
  return [{ role: "system", content: `REF-ID: ${refId}`, timestamp: baseTs }, ...turns];
@@ -15804,17 +15889,62 @@ function withRefId(refId, turns, baseTs) {
15804
15889
  function renderSessionJsonl(refId, turns, baseTs) {
15805
15890
  return withRefId(refId, turns, baseTs).map((t) => JSON.stringify(t)).join("\n");
15806
15891
  }
15807
- async function retainLiveSession(client, sessionId2, turns, startTs, harness) {
15892
+ async function supportsAppend(client) {
15893
+ try {
15894
+ return await client.supportsIdempotentRetain();
15895
+ } catch {
15896
+ return false;
15897
+ }
15898
+ }
15899
+ var writeBacks = /* @__PURE__ */ new WeakMap();
15900
+ function serialize(cursors, sessionId2, write2) {
15901
+ const perSession = writeBacks.get(cursors) ?? /* @__PURE__ */ new Map();
15902
+ writeBacks.set(cursors, perSession);
15903
+ const next = (perSession.get(sessionId2) ?? Promise.resolve()).then(write2, write2);
15904
+ const tail = next.catch(() => {
15905
+ });
15906
+ perSession.set(sessionId2, tail);
15907
+ void tail.then(() => {
15908
+ if (perSession.get(sessionId2) === tail) perSession.delete(sessionId2);
15909
+ });
15910
+ return next;
15911
+ }
15912
+ async function retainLiveSession(client, sessionId2, turns, startTs, harness, opts = {}) {
15913
+ const cursors = opts.cursors;
15914
+ if (!cursors) return writeSession(client, sessionId2, turns, startTs, harness);
15915
+ return serialize(
15916
+ cursors,
15917
+ sessionId2,
15918
+ () => writeSession(client, sessionId2, turns, startTs, harness, cursors)
15919
+ );
15920
+ }
15921
+ async function writeSession(client, sessionId2, turns, startTs, harness, cursors) {
15808
15922
  const refId = `conversation:${sessionId2}`;
15923
+ const appendSupported = Boolean(cursors) && await supportsAppend(client);
15924
+ const plan = planRetain(turns, cursors?.read(sessionId2), { appendSupported, bank: client.bank });
15925
+ if (plan.mode === "skip") return;
15926
+ const content = plan.mode === "append" ? turns.slice(plan.fromTurn).map((t) => JSON.stringify(t)).join("\n") : renderSessionJsonl(refId, turns, startTs);
15927
+ const next = {
15928
+ turns: turns.length,
15929
+ fingerprint: fingerprintTurns(turns, turns.length),
15930
+ bank: client.bank
15931
+ };
15932
+ cursors?.write(sessionId2, { ...next, dirty: true });
15809
15933
  await client.retain(
15810
- renderSessionJsonl(refId, turns, startTs),
15934
+ content,
15811
15935
  "coding agent session",
15812
15936
  refId,
15813
15937
  ["source:chat", ...harness ? [`harness:${harness}`] : []],
15814
15938
  "conversation",
15815
15939
  {
15816
15940
  timestamp: startTs,
15817
- async: true,
15941
+ updateMode: plan.mode === "append" ? "append" : void 0,
15942
+ // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
15943
+ // the original operation instead of extracting (or appending) twice.
15944
+ operationId: uuidV5(`${client.bank}
15945
+ ${refId}
15946
+ ${plan.mode}
15947
+ ${content}`),
15818
15948
  metadata: {
15819
15949
  source: "chat",
15820
15950
  session_id: sessionId2,
@@ -15823,6 +15953,7 @@ async function retainLiveSession(client, sessionId2, turns, startTs, harness) {
15823
15953
  }
15824
15954
  }
15825
15955
  );
15956
+ cursors?.write(sessionId2, next);
15826
15957
  }
15827
15958
 
15828
15959
  // src/core/session-start.ts
@@ -15924,8 +16055,7 @@ async function buildSessionStartContext(args) {
15924
16055
  "hindsight codebase-survey baseline",
15925
16056
  `${SURVEY_BASELINE_PREFIX}${sha}`,
15926
16057
  [SURVEY_BASELINE_TAG],
15927
- "survey",
15928
- { async: true }
16058
+ "survey"
15929
16059
  )
15930
16060
  ).catch(() => {
15931
16061
  });
@@ -15945,7 +16075,7 @@ async function buildSessionStartContext(args) {
15945
16075
  cold = docIds !== void 0 ? docIds.size === 0 : void 0;
15946
16076
  gitDocIds = docIds;
15947
16077
  if (docIds !== void 0) {
15948
- startSeed(cwd, { limit: cfg.seedLimit });
16078
+ startSeed(cwd, { limit: cfg.seedLimit, harness });
15949
16079
  if (docIds.size === 0) {
15950
16080
  if (cfg.codebaseSurvey !== false) {
15951
16081
  startSurvey(cwd, {
@@ -16150,6 +16280,8 @@ var RuntimeCore = class {
16150
16280
  turnCount = /* @__PURE__ */ new Map();
16151
16281
  // sessionId -> user-turn counter (cadence)
16152
16282
  sessionState = /* @__PURE__ */ new Map();
16283
+ /** Live write-back cursors. In memory, unlike the hook harnesses': this host outlives the session. */
16284
+ cursors = memoryCursorStore();
16153
16285
  /** Pulls a session's CURRENT transcript from the host (set by the adapter); see onSessionIdle. */
16154
16286
  fetchTranscript;
16155
16287
  lastInjection = "";
@@ -16305,7 +16437,9 @@ var RuntimeCore = class {
16305
16437
  /** Fire-and-forget upsert of the session transcript; never throws into the host. */
16306
16438
  retain(sessionId2, turns, startTs, trigger = "turn") {
16307
16439
  const t0 = Date.now();
16308
- void retainLiveSession(this.client, sessionId2, turns, startTs, this.harness).then(
16440
+ void retainLiveSession(this.client, sessionId2, turns, startTs, this.harness, {
16441
+ cursors: this.cursors
16442
+ }).then(
16309
16443
  () => diag(this.harness, "retain_ok", {
16310
16444
  ms: Date.now() - t0,
16311
16445
  turns: turns.length,
@@ -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
  }
@@ -1033,15 +1073,79 @@ async function runHook(spec, makeClient = (o) => new HindsightClient(o)) {
1033
1073
  }
1034
1074
 
1035
1075
  // src/core/retain-hook.ts
1036
- import { readFileSync as readFileSync5 } from "fs";
1076
+ import { readFileSync as readFileSync4 } from "fs";
1077
+
1078
+ // src/core/retain-cursor.ts
1079
+ import { createHash } from "crypto";
1080
+
1081
+ // src/core/uuid.ts
1082
+ import { createHash as createHash2 } from "crypto";
1037
1083
 
1038
1084
  // src/core/daemon.ts
1039
1085
  import { execFileSync as execFileSync2, spawn as realSpawn2 } from "child_process";
1040
1086
  import { dirname as dirname5, join as join6 } from "path";
1041
1087
  import { fileURLToPath as fileURLToPath2 } from "url";
1042
1088
 
1043
- // src/core/transcript.ts
1044
- import { readFileSync as readFileSync4 } from "fs";
1089
+ // src/core/jsonl.ts
1090
+ import { closeSync, openSync, readSync, statSync } from "fs";
1091
+ import { StringDecoder } from "string_decoder";
1092
+ var CHUNK_BYTES = 64 * 1024;
1093
+ var MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024;
1094
+ function readJsonlTail(path, opts) {
1095
+ const maxBytes = opts.maxBytes ?? MAX_TRANSCRIPT_BYTES;
1096
+ let size;
1097
+ try {
1098
+ size = statSync(path).size;
1099
+ } catch {
1100
+ return { lines: emptyLines(), skippedBytes: 0 };
1101
+ }
1102
+ const skippedBytes = size > maxBytes ? size - maxBytes : 0;
1103
+ if (skippedBytes > 0) {
1104
+ log.warn(opts.scope, "transcript too large \u2014 retaining the most recent portion only", {
1105
+ path,
1106
+ sizeBytes: size,
1107
+ skippedBytes
1108
+ });
1109
+ }
1110
+ return { lines: streamLines(path, skippedBytes), skippedBytes };
1111
+ }
1112
+ function* emptyLines() {
1113
+ }
1114
+ function* streamLines(path, start) {
1115
+ let fd;
1116
+ try {
1117
+ fd = openSync(path, "r");
1118
+ } catch {
1119
+ return;
1120
+ }
1121
+ try {
1122
+ const buffer = Buffer.allocUnsafe(CHUNK_BYTES);
1123
+ const decoder = new StringDecoder("utf8");
1124
+ let pending = "";
1125
+ let position = start > 0 ? start - 1 : 0;
1126
+ let dropPartial = start > 0;
1127
+ for (; ; ) {
1128
+ const bytesRead = readSync(fd, buffer, 0, buffer.length, position);
1129
+ if (bytesRead <= 0) break;
1130
+ position += bytesRead;
1131
+ pending += decoder.write(buffer.subarray(0, bytesRead));
1132
+ let newline;
1133
+ while ((newline = pending.indexOf("\n")) !== -1) {
1134
+ const line = pending.slice(0, newline);
1135
+ pending = pending.slice(newline + 1);
1136
+ if (dropPartial) {
1137
+ dropPartial = false;
1138
+ continue;
1139
+ }
1140
+ yield line;
1141
+ }
1142
+ }
1143
+ pending += decoder.end();
1144
+ if (pending && !dropPartial) yield pending;
1145
+ } finally {
1146
+ closeSync(fd);
1147
+ }
1148
+ }
1045
1149
 
1046
1150
  // src/core/transcript-util.ts
1047
1151
  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;
@@ -1079,7 +1183,7 @@ function actionLine(tool, input) {
1079
1183
  }
1080
1184
 
1081
1185
  // src/core/session-start.ts
1082
- import { readFileSync as readFileSync7 } from "fs";
1186
+ import { readFileSync as readFileSync6 } from "fs";
1083
1187
 
1084
1188
  // src/core/git.ts
1085
1189
  import { execFileSync as execFileSync3 } from "child_process";
@@ -1096,13 +1200,12 @@ import { delimiter, dirname as dirname6, join as join7 } from "path";
1096
1200
  import { fileURLToPath as fileURLToPath3 } from "url";
1097
1201
 
1098
1202
  // src/core/skill-sync.ts
1099
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync6 } from "fs";
1203
+ import { cpSync, existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
1100
1204
  import { homedir as homedir4 } from "os";
1101
1205
  import { dirname as dirname7, join as join8 } from "path";
1102
1206
  import { fileURLToPath as fileURLToPath4 } from "url";
1103
1207
 
1104
1208
  // src/core/transcript-codex.ts
1105
- import { readFileSync as readFileSync8 } from "fs";
1106
1209
  function isSyntheticUserText(text) {
1107
1210
  const s = text.trimStart();
1108
1211
  return s.startsWith("# AGENTS.md instructions for ") || s.startsWith("<environment_context>");
@@ -1111,14 +1214,8 @@ function messageText(payload) {
1111
1214
  return (payload.content || []).filter((c) => c && typeof c.text === "string").map((c) => c.text).join("\n");
1112
1215
  }
1113
1216
  function readCodexTranscript(path) {
1114
- let raw;
1115
- try {
1116
- raw = readFileSync8(path, "utf8");
1117
- } catch {
1118
- return [];
1119
- }
1120
1217
  const turns = [];
1121
- for (const rawLine of raw.split("\n")) {
1218
+ for (const rawLine of readJsonlTail(path, { scope: "codex" }).lines) {
1122
1219
  const trimmed = rawLine.trim();
1123
1220
  if (!trimmed) continue;
1124
1221
  let parsed;
@@ -1152,7 +1249,6 @@ function readCodexTranscript(path) {
1152
1249
  }
1153
1250
 
1154
1251
  // src/core/transcript-cursor.ts
1155
- import { readFileSync as readFileSync9 } from "fs";
1156
1252
  function withTimestamp(turn, timestamp) {
1157
1253
  return timestamp ? { ...turn, timestamp } : turn;
1158
1254
  }
@@ -1162,14 +1258,8 @@ function textFrom(content) {
1162
1258
  return content.filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n");
1163
1259
  }
1164
1260
  function readCursorTranscript(path) {
1165
- let raw;
1166
- try {
1167
- raw = readFileSync9(path, "utf8");
1168
- } catch {
1169
- return [];
1170
- }
1171
1261
  const turns = [];
1172
- for (const rawLine of raw.split("\n")) {
1262
+ for (const rawLine of readJsonlTail(path, { scope: "cursor-cli" }).lines) {
1173
1263
  let parsed;
1174
1264
  try {
1175
1265
  parsed = JSON.parse(rawLine);
@@ -1205,17 +1295,10 @@ function readCursorTranscript(path) {
1205
1295
  }
1206
1296
 
1207
1297
  // src/core/transcript-antigravity.ts
1208
- import { readFileSync as readFileSync10 } from "fs";
1209
1298
  function readAntigravityTranscript(path) {
1210
1299
  if (!path) return [];
1211
- let raw;
1212
- try {
1213
- raw = readFileSync10(path, "utf8");
1214
- } catch {
1215
- return [];
1216
- }
1217
1300
  const turns = [];
1218
- for (const line of raw.split("\n")) {
1301
+ for (const line of readJsonlTail(path, { scope: "antigravity-cli" }).lines) {
1219
1302
  try {
1220
1303
  const event = JSON.parse(line);
1221
1304
  const role = event.role ?? event.message?.role ?? event.type;
@@ -1236,16 +1319,9 @@ function readAntigravityTranscript(path) {
1236
1319
  }
1237
1320
 
1238
1321
  // src/core/transcript-copilot.ts
1239
- import { readFileSync as readFileSync11 } from "fs";
1240
1322
  function readCopilotTranscript(path) {
1241
- let raw;
1242
- try {
1243
- raw = readFileSync11(path, "utf8");
1244
- } catch {
1245
- return [];
1246
- }
1247
1323
  const turns = [];
1248
- for (const rawLine of raw.split("\n")) {
1324
+ for (const rawLine of readJsonlTail(path, { scope: "copilot-cli" }).lines) {
1249
1325
  try {
1250
1326
  const event = JSON.parse(rawLine);
1251
1327
  const role = event.type === "user.message" ? "user" : event.type === "assistant.message" ? "assistant" : void 0;
@@ -1259,7 +1335,7 @@ function readCopilotTranscript(path) {
1259
1335
  }
1260
1336
 
1261
1337
  // src/core/transcript-grok.ts
1262
- import { existsSync as existsSync4, readFileSync as readFileSync12, readdirSync } from "fs";
1338
+ import { existsSync as existsSync4, readFileSync as readFileSync7, readdirSync } from "fs";
1263
1339
  import { homedir as homedir5 } from "os";
1264
1340
  import { join as join9 } from "path";
1265
1341
  var CHAT_HISTORY = "chat_history.jsonl";
@@ -1270,7 +1346,7 @@ function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME ||
1270
1346
  try {
1271
1347
  for (const candidate of readdirSync(sessionsDir)) {
1272
1348
  const directory = join9(sessionsDir, candidate);
1273
- if (readFileSync12(join9(directory, ".cwd"), "utf8").trim() === cwd) {
1349
+ if (readFileSync7(join9(directory, ".cwd"), "utf8").trim() === cwd) {
1274
1350
  return join9(directory, sessionId, CHAT_HISTORY);
1275
1351
  }
1276
1352
  }
@@ -1279,14 +1355,8 @@ function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME ||
1279
1355
  return direct;
1280
1356
  }
1281
1357
  function readGrokTranscript(path) {
1282
- let raw;
1283
- try {
1284
- raw = readFileSync12(path, "utf8");
1285
- } catch {
1286
- return [];
1287
- }
1288
1358
  const turns = [];
1289
- for (const rawLine of raw.split("\n")) {
1359
+ for (const rawLine of readJsonlTail(path, { scope: "grok-build" }).lines) {
1290
1360
  try {
1291
1361
  const event = JSON.parse(rawLine);
1292
1362
  if (event.type !== "user" && event.type !== "assistant") continue;