@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.
package/dist/index.js CHANGED
@@ -4,6 +4,9 @@ var __export = (target, all) => {
4
4
  __defProp(target, name, { get: all[name], enumerable: true });
5
5
  };
6
6
 
7
+ // src/harness/plugin-entry.ts
8
+ import { posix, win32 } from "path";
9
+
7
10
  // src/core/bank.ts
8
11
  import { execFileSync } from "child_process";
9
12
  import { homedir } from "os";
@@ -431,8 +434,22 @@ var CODING_BANK_TEMPLATE = {
431
434
 
432
435
  // src/core/util.ts
433
436
  var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
437
+ function semverGte(version3, min) {
438
+ const parts = (v) => {
439
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
440
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
441
+ };
442
+ const a = version3 ? parts(version3) : void 0;
443
+ const b = parts(min);
444
+ if (!a || !b) return false;
445
+ for (let i = 0; i < 3; i++) {
446
+ if (a[i] !== b[i]) return a[i] > b[i];
447
+ }
448
+ return true;
449
+ }
434
450
 
435
451
  // src/core/hindsight.ts
452
+ var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
436
453
  var KnowledgePagesUnavailableError = class extends Error {
437
454
  code = "knowledge_pages_unavailable";
438
455
  constructor() {
@@ -449,6 +466,8 @@ var HindsightClient = class {
449
466
  // async operation ids collected by retain(), for drain()
450
467
  /** Tri-state capability probe: unknown until the first page request, then cached. */
451
468
  knowledgePagesSupported;
469
+ /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
470
+ idempotentRetain;
452
471
  log;
453
472
  constructor(o) {
454
473
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
@@ -477,7 +496,8 @@ var HindsightClient = class {
477
496
  throw new Error(`${method} ${url3} -> ${r.status} ${await r.text()}`);
478
497
  return r;
479
498
  }
480
- /** Retain one memory. Async by default: enqueue extraction server-side and collect its op-id for drain(). */
499
+ /** Retain one memory. ALWAYS async: enqueue extraction server-side and collect its op-id for
500
+ * drain(). Nothing in this plugin can afford to block a coding agent's hook on extraction. */
481
501
  async retain(content, context, documentId, tags, strategy, opts = {}) {
482
502
  const item = {
483
503
  content,
@@ -488,14 +508,36 @@ var HindsightClient = class {
488
508
  };
489
509
  if (opts.timestamp) item.timestamp = opts.timestamp;
490
510
  if (opts.metadata) item.metadata = opts.metadata;
491
- const isAsync = opts.async !== false;
492
- const r = await this.req("POST", this.bankUrl("/memories"), { items: [item], async: isAsync });
493
- if (isAsync) {
494
- try {
495
- const j = await r.json();
496
- if (j.operation_id) this.opIds.push(j.operation_id);
497
- } catch {
498
- }
511
+ if (opts.updateMode) item.update_mode = opts.updateMode;
512
+ const body = { items: [item], async: true };
513
+ if (opts.operationId) body.operation_id = opts.operationId;
514
+ const r = await this.req("POST", this.bankUrl("/memories"), body);
515
+ try {
516
+ const j = await r.json();
517
+ if (j.operation_id) this.opIds.push(j.operation_id);
518
+ } catch {
519
+ }
520
+ }
521
+ /**
522
+ * Whether this server honours `operation_id` on an async retain, and can therefore be appended to
523
+ * safely (see MIN_IDEMPOTENT_RETAIN_VERSION). Probed once per client via GET /version; anything
524
+ * unreachable, unparseable or older answers "no", which costs efficiency, never correctness.
525
+ */
526
+ async supportsIdempotentRetain() {
527
+ if (this.idempotentRetain === void 0) {
528
+ this.idempotentRetain = await this.probeIdempotentRetain();
529
+ this.log(`server retain idempotency: ${this.idempotentRetain ? "supported" : "unavailable"}`);
530
+ }
531
+ return this.idempotentRetain;
532
+ }
533
+ async probeIdempotentRetain() {
534
+ try {
535
+ const r = await this.req("GET", `${this.apiUrl}/version`);
536
+ if (!r.ok) return false;
537
+ const j = await r.json();
538
+ return semverGte(j.api_version, MIN_IDEMPOTENT_RETAIN_VERSION);
539
+ } catch {
540
+ return false;
499
541
  }
500
542
  }
501
543
  /**
@@ -783,8 +825,7 @@ var HindsightClient = class {
783
825
  "initiative marker",
784
826
  markerId,
785
827
  ["knowledge:feature-work", `relatedPageId:${pageId}`],
786
- "document",
787
- { async: true }
828
+ "document"
788
829
  );
789
830
  return { page_id: pageId };
790
831
  }
@@ -15789,7 +15830,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15789
15830
  docId,
15790
15831
  ["source:upload", ...opts.harness ? [`harness:${opts.harness}`] : []],
15791
15832
  "document",
15792
- { async: true, metadata: opts.harness ? { harness: opts.harness } : void 0 }
15833
+ { metadata: opts.harness ? { harness: opts.harness } : void 0 }
15793
15834
  );
15794
15835
  return { ok: true, doc_id: docId };
15795
15836
  })
@@ -15797,6 +15838,51 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15797
15838
  ];
15798
15839
  }
15799
15840
 
15841
+ // src/core/retain-cursor.ts
15842
+ import { createHash } from "crypto";
15843
+ function fingerprintTurns(turns, count) {
15844
+ const h = createHash("sha1").update(String(count));
15845
+ for (let i = 0; i < count; i++) h.update("\n" + JSON.stringify(turns[i]));
15846
+ return h.digest("hex");
15847
+ }
15848
+ function planRetain(turns, cursor, opts) {
15849
+ if (!turns.length) return { mode: "skip" };
15850
+ if (!opts.appendSupported || !cursor || cursor.dirty) return { mode: "replace" };
15851
+ if (cursor.bank !== opts.bank) return { mode: "replace" };
15852
+ if (cursor.turns > turns.length) return { mode: "replace" };
15853
+ if (fingerprintTurns(turns, cursor.turns) !== cursor.fingerprint) return { mode: "replace" };
15854
+ if (cursor.turns === turns.length) return { mode: "skip" };
15855
+ return { mode: "append", fromTurn: cursor.turns };
15856
+ }
15857
+ function memoryCursorStore() {
15858
+ const cursors = /* @__PURE__ */ new Map();
15859
+ return {
15860
+ read: (sessionId) => cursors.get(sessionId),
15861
+ write: (sessionId, cursor) => void cursors.set(sessionId, cursor)
15862
+ };
15863
+ }
15864
+
15865
+ // src/core/uuid.ts
15866
+ import { createHash as createHash2 } from "crypto";
15867
+ var HINDSIGHT_NAMESPACE = "e75686a4-e923-4326-a0d1-358f1c6c3eb4";
15868
+ function uuidV5(name, namespace = HINDSIGHT_NAMESPACE) {
15869
+ const ns = Buffer.from(namespace.replace(/-/g, ""), "hex");
15870
+ if (ns.length !== 16) throw new Error(`invalid UUID namespace: ${namespace}`);
15871
+ const bytes = Buffer.from(
15872
+ createHash2("sha1").update(ns).update(Buffer.from(name, "utf8")).digest().subarray(0, 16)
15873
+ );
15874
+ bytes[6] = bytes[6] & 15 | 80;
15875
+ bytes[8] = bytes[8] & 63 | 128;
15876
+ const hex5 = bytes.toString("hex");
15877
+ return [
15878
+ hex5.slice(0, 8),
15879
+ hex5.slice(8, 12),
15880
+ hex5.slice(12, 16),
15881
+ hex5.slice(16, 20),
15882
+ hex5.slice(20)
15883
+ ].join("-");
15884
+ }
15885
+
15800
15886
  // src/core/chat.ts
15801
15887
  function withRefId(refId, turns, baseTs) {
15802
15888
  return [{ role: "system", content: `REF-ID: ${refId}`, timestamp: baseTs }, ...turns];
@@ -15804,17 +15890,62 @@ function withRefId(refId, turns, baseTs) {
15804
15890
  function renderSessionJsonl(refId, turns, baseTs) {
15805
15891
  return withRefId(refId, turns, baseTs).map((t) => JSON.stringify(t)).join("\n");
15806
15892
  }
15807
- async function retainLiveSession(client, sessionId, turns, startTs, harness) {
15893
+ async function supportsAppend(client) {
15894
+ try {
15895
+ return await client.supportsIdempotentRetain();
15896
+ } catch {
15897
+ return false;
15898
+ }
15899
+ }
15900
+ var writeBacks = /* @__PURE__ */ new WeakMap();
15901
+ function serialize(cursors, sessionId, write2) {
15902
+ const perSession = writeBacks.get(cursors) ?? /* @__PURE__ */ new Map();
15903
+ writeBacks.set(cursors, perSession);
15904
+ const next = (perSession.get(sessionId) ?? Promise.resolve()).then(write2, write2);
15905
+ const tail = next.catch(() => {
15906
+ });
15907
+ perSession.set(sessionId, tail);
15908
+ void tail.then(() => {
15909
+ if (perSession.get(sessionId) === tail) perSession.delete(sessionId);
15910
+ });
15911
+ return next;
15912
+ }
15913
+ async function retainLiveSession(client, sessionId, turns, startTs, harness, opts = {}) {
15914
+ const cursors = opts.cursors;
15915
+ if (!cursors) return writeSession(client, sessionId, turns, startTs, harness);
15916
+ return serialize(
15917
+ cursors,
15918
+ sessionId,
15919
+ () => writeSession(client, sessionId, turns, startTs, harness, cursors)
15920
+ );
15921
+ }
15922
+ async function writeSession(client, sessionId, turns, startTs, harness, cursors) {
15808
15923
  const refId = `conversation:${sessionId}`;
15924
+ const appendSupported = Boolean(cursors) && await supportsAppend(client);
15925
+ const plan = planRetain(turns, cursors?.read(sessionId), { appendSupported, bank: client.bank });
15926
+ if (plan.mode === "skip") return;
15927
+ const content = plan.mode === "append" ? turns.slice(plan.fromTurn).map((t) => JSON.stringify(t)).join("\n") : renderSessionJsonl(refId, turns, startTs);
15928
+ const next = {
15929
+ turns: turns.length,
15930
+ fingerprint: fingerprintTurns(turns, turns.length),
15931
+ bank: client.bank
15932
+ };
15933
+ cursors?.write(sessionId, { ...next, dirty: true });
15809
15934
  await client.retain(
15810
- renderSessionJsonl(refId, turns, startTs),
15935
+ content,
15811
15936
  "coding agent session",
15812
15937
  refId,
15813
15938
  ["source:chat", ...harness ? [`harness:${harness}`] : []],
15814
15939
  "conversation",
15815
15940
  {
15816
15941
  timestamp: startTs,
15817
- async: true,
15942
+ updateMode: plan.mode === "append" ? "append" : void 0,
15943
+ // Identity of THIS payload: a resubmission of the same bytes is collapsed server-side into
15944
+ // the original operation instead of extracting (or appending) twice.
15945
+ operationId: uuidV5(`${client.bank}
15946
+ ${refId}
15947
+ ${plan.mode}
15948
+ ${content}`),
15818
15949
  metadata: {
15819
15950
  source: "chat",
15820
15951
  session_id: sessionId,
@@ -15823,6 +15954,7 @@ async function retainLiveSession(client, sessionId, turns, startTs, harness) {
15823
15954
  }
15824
15955
  }
15825
15956
  );
15957
+ cursors?.write(sessionId, next);
15826
15958
  }
15827
15959
 
15828
15960
  // src/core/session-start.ts
@@ -15924,8 +16056,7 @@ async function buildSessionStartContext(args) {
15924
16056
  "hindsight codebase-survey baseline",
15925
16057
  `${SURVEY_BASELINE_PREFIX}${sha}`,
15926
16058
  [SURVEY_BASELINE_TAG],
15927
- "survey",
15928
- { async: true }
16059
+ "survey"
15929
16060
  )
15930
16061
  ).catch(() => {
15931
16062
  });
@@ -16150,6 +16281,8 @@ var RuntimeCore = class {
16150
16281
  turnCount = /* @__PURE__ */ new Map();
16151
16282
  // sessionId -> user-turn counter (cadence)
16152
16283
  sessionState = /* @__PURE__ */ new Map();
16284
+ /** Live write-back cursors. In memory, unlike the hook harnesses': this host outlives the session. */
16285
+ cursors = memoryCursorStore();
16153
16286
  /** Pulls a session's CURRENT transcript from the host (set by the adapter); see onSessionIdle. */
16154
16287
  fetchTranscript;
16155
16288
  lastInjection = "";
@@ -16305,7 +16438,9 @@ var RuntimeCore = class {
16305
16438
  /** Fire-and-forget upsert of the session transcript; never throws into the host. */
16306
16439
  retain(sessionId, turns, startTs, trigger = "turn") {
16307
16440
  const t0 = Date.now();
16308
- void retainLiveSession(this.client, sessionId, turns, startTs, this.harness).then(
16441
+ void retainLiveSession(this.client, sessionId, turns, startTs, this.harness, {
16442
+ cursors: this.cursors
16443
+ }).then(
16309
16444
  () => diag(this.harness, "retain_ok", {
16310
16445
  ms: Date.now() - t0,
16311
16446
  turns: turns.length,
@@ -28886,9 +29021,16 @@ var opencodeAdapter = { name: "opencode", chatReader, createRuntime };
28886
29021
 
28887
29022
  // src/harness/plugin-entry.ts
28888
29023
  var TOAST_MOUNT_GRACE_MS = 3e3;
29024
+ function isFilesystemRoot(path) {
29025
+ return posix.parse(path).root === path || win32.parse(path).root === path;
29026
+ }
29027
+ function resolveProjectDirectory(input) {
29028
+ const worktree = input?.worktree;
29029
+ return worktree && !isFilesystemRoot(worktree) ? worktree : input?.directory;
29030
+ }
28889
29031
  function createPluginEntry(harness) {
28890
29032
  return async (input) => {
28891
- const projectDir = input?.worktree || input?.directory;
29033
+ const projectDir = resolveProjectDirectory(input);
28892
29034
  let cfg = loadConfig({ harness });
28893
29035
  if (cfg.disabled) return {};
28894
29036
  const resolved = applyBankConfig(cfg, deriveBankId(cfg, projectDir || process.cwd(), harness));