@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/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";
@@ -242,7 +245,9 @@ function readEnvConfig(env = process.env) {
242
245
  function loadConfig(opts = {}) {
243
246
  const o = typeof opts === "string" ? { path: opts } : opts;
244
247
  const withEnv = applyLayer({}, readEnvConfig(), o.harness);
245
- return resolveConfig(applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness));
248
+ const raw = applyLayer(withEnv, readRaw(o.path ?? CONFIG_PATH), o.harness);
249
+ if (!raw.harness && o.harness) raw.harness = o.harness;
250
+ return resolveConfig(raw);
246
251
  }
247
252
  var BANK_OVERRIDE_EXCLUDED = [
248
253
  "bankId",
@@ -311,7 +316,7 @@ var GITLOG_MISSION = "You are ingesting an aggregated block of git commit MESSAG
311
316
  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.`;
312
317
  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.";
313
318
  var DOCUMENT_MISSION = "You are ingesting a standalone document (notes, docs, or structural findings). Extract the concrete facts, concepts, and structure it describes.";
314
- 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.";
319
+ 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.";
315
320
  var RETAIN_STRATEGIES = {
316
321
  git: { retain_mission: GIT_MISSION, retain_extraction_mode: "verbose" },
317
322
  // ONE big aggregated document (last N commit messages, no diffs) -> a larger chunk size so it stays
@@ -429,8 +434,22 @@ var CODING_BANK_TEMPLATE = {
429
434
 
430
435
  // src/core/util.ts
431
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
+ }
432
450
 
433
451
  // src/core/hindsight.ts
452
+ var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
434
453
  var KnowledgePagesUnavailableError = class extends Error {
435
454
  code = "knowledge_pages_unavailable";
436
455
  constructor() {
@@ -447,6 +466,8 @@ var HindsightClient = class {
447
466
  // async operation ids collected by retain(), for drain()
448
467
  /** Tri-state capability probe: unknown until the first page request, then cached. */
449
468
  knowledgePagesSupported;
469
+ /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
470
+ idempotentRetain;
450
471
  log;
451
472
  constructor(o) {
452
473
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
@@ -475,7 +496,8 @@ var HindsightClient = class {
475
496
  throw new Error(`${method} ${url3} -> ${r.status} ${await r.text()}`);
476
497
  return r;
477
498
  }
478
- /** 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. */
479
501
  async retain(content, context, documentId, tags, strategy, opts = {}) {
480
502
  const item = {
481
503
  content,
@@ -486,14 +508,36 @@ var HindsightClient = class {
486
508
  };
487
509
  if (opts.timestamp) item.timestamp = opts.timestamp;
488
510
  if (opts.metadata) item.metadata = opts.metadata;
489
- const isAsync = opts.async !== false;
490
- const r = await this.req("POST", this.bankUrl("/memories"), { items: [item], async: isAsync });
491
- if (isAsync) {
492
- try {
493
- const j = await r.json();
494
- if (j.operation_id) this.opIds.push(j.operation_id);
495
- } catch {
496
- }
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;
497
541
  }
498
542
  }
499
543
  /**
@@ -781,8 +825,7 @@ var HindsightClient = class {
781
825
  "initiative marker",
782
826
  markerId,
783
827
  ["knowledge:feature-work", `relatedPageId:${pageId}`],
784
- "document",
785
- { async: true }
828
+ "document"
786
829
  );
787
830
  return { page_id: pageId };
788
831
  }
@@ -15787,7 +15830,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15787
15830
  docId,
15788
15831
  ["source:upload", ...opts.harness ? [`harness:${opts.harness}`] : []],
15789
15832
  "document",
15790
- { async: true, metadata: opts.harness ? { harness: opts.harness } : void 0 }
15833
+ { metadata: opts.harness ? { harness: opts.harness } : void 0 }
15791
15834
  );
15792
15835
  return { ok: true, doc_id: docId };
15793
15836
  })
@@ -15795,6 +15838,51 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
15795
15838
  ];
15796
15839
  }
15797
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
+
15798
15886
  // src/core/chat.ts
15799
15887
  function withRefId(refId, turns, baseTs) {
15800
15888
  return [{ role: "system", content: `REF-ID: ${refId}`, timestamp: baseTs }, ...turns];
@@ -15802,17 +15890,62 @@ function withRefId(refId, turns, baseTs) {
15802
15890
  function renderSessionJsonl(refId, turns, baseTs) {
15803
15891
  return withRefId(refId, turns, baseTs).map((t) => JSON.stringify(t)).join("\n");
15804
15892
  }
15805
- 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) {
15806
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 });
15807
15934
  await client.retain(
15808
- renderSessionJsonl(refId, turns, startTs),
15935
+ content,
15809
15936
  "coding agent session",
15810
15937
  refId,
15811
15938
  ["source:chat", ...harness ? [`harness:${harness}`] : []],
15812
15939
  "conversation",
15813
15940
  {
15814
15941
  timestamp: startTs,
15815
- 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}`),
15816
15949
  metadata: {
15817
15950
  source: "chat",
15818
15951
  session_id: sessionId,
@@ -15821,6 +15954,7 @@ async function retainLiveSession(client, sessionId, turns, startTs, harness) {
15821
15954
  }
15822
15955
  }
15823
15956
  );
15957
+ cursors?.write(sessionId, next);
15824
15958
  }
15825
15959
 
15826
15960
  // src/core/session-start.ts
@@ -15922,8 +16056,7 @@ async function buildSessionStartContext(args) {
15922
16056
  "hindsight codebase-survey baseline",
15923
16057
  `${SURVEY_BASELINE_PREFIX}${sha}`,
15924
16058
  [SURVEY_BASELINE_TAG],
15925
- "survey",
15926
- { async: true }
16059
+ "survey"
15927
16060
  )
15928
16061
  ).catch(() => {
15929
16062
  });
@@ -15943,7 +16076,7 @@ async function buildSessionStartContext(args) {
15943
16076
  cold = docIds !== void 0 ? docIds.size === 0 : void 0;
15944
16077
  gitDocIds = docIds;
15945
16078
  if (docIds !== void 0) {
15946
- startSeed(cwd, { limit: cfg.seedLimit });
16079
+ startSeed(cwd, { limit: cfg.seedLimit, harness });
15947
16080
  if (docIds.size === 0) {
15948
16081
  if (cfg.codebaseSurvey !== false) {
15949
16082
  startSurvey(cwd, {
@@ -16148,6 +16281,8 @@ var RuntimeCore = class {
16148
16281
  turnCount = /* @__PURE__ */ new Map();
16149
16282
  // sessionId -> user-turn counter (cadence)
16150
16283
  sessionState = /* @__PURE__ */ new Map();
16284
+ /** Live write-back cursors. In memory, unlike the hook harnesses': this host outlives the session. */
16285
+ cursors = memoryCursorStore();
16151
16286
  /** Pulls a session's CURRENT transcript from the host (set by the adapter); see onSessionIdle. */
16152
16287
  fetchTranscript;
16153
16288
  lastInjection = "";
@@ -16303,7 +16438,9 @@ var RuntimeCore = class {
16303
16438
  /** Fire-and-forget upsert of the session transcript; never throws into the host. */
16304
16439
  retain(sessionId, turns, startTs, trigger = "turn") {
16305
16440
  const t0 = Date.now();
16306
- 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(
16307
16444
  () => diag(this.harness, "retain_ok", {
16308
16445
  ms: Date.now() - t0,
16309
16446
  turns: turns.length,
@@ -28884,9 +29021,16 @@ var opencodeAdapter = { name: "opencode", chatReader, createRuntime };
28884
29021
 
28885
29022
  // src/harness/plugin-entry.ts
28886
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
+ }
28887
29031
  function createPluginEntry(harness) {
28888
29032
  return async (input) => {
28889
- const projectDir = input?.worktree || input?.directory;
29033
+ const projectDir = resolveProjectDirectory(input);
28890
29034
  let cfg = loadConfig({ harness });
28891
29035
  if (cfg.disabled) return {};
28892
29036
  const resolved = applyBankConfig(cfg, deriveBankId(cfg, projectDir || process.cwd(), harness));