@vectorize-io/hindsight-coding-agents 0.1.1 → 0.2.0

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/grok-hook.js CHANGED
@@ -7,9 +7,25 @@ import { existsSync, readFileSync as readFileSync3 } from "fs";
7
7
  import { execFileSync } from "child_process";
8
8
  import { homedir } from "os";
9
9
  import { basename, dirname, join, normalize, sep } from "path";
10
+
11
+ // src/core/template.ts
12
+ var PLACEHOLDER = /\{([a-zA-Z_]+)\}/g;
13
+ function applyTemplate(template, resolvers, what) {
14
+ return template.replace(PLACEHOLDER, (_, name) => {
15
+ const resolve2 = resolvers[name];
16
+ if (!resolve2) {
17
+ console.error(
18
+ `hindsight: unknown ${what} placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
19
+ );
20
+ return "unknown";
21
+ }
22
+ return resolve2();
23
+ });
24
+ }
25
+
26
+ // src/core/bank.ts
10
27
  var DEFAULT_BANK_NAME = "coding";
11
28
  var DEFAULT_TEMPLATE = "coding-agent::{gitProject}";
12
- var PLACEHOLDER = /\{([a-zA-Z]+)\}/g;
13
29
  function getProjectRootFromGit(directory) {
14
30
  if (!directory) return null;
15
31
  try {
@@ -55,16 +71,7 @@ function deriveBankId(config, directory, harness = "coding") {
55
71
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
56
72
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
57
73
  };
58
- return (config.bankIdTemplate || DEFAULT_TEMPLATE).replace(PLACEHOLDER, (_, name) => {
59
- const r = resolvers[name];
60
- if (!r) {
61
- console.error(
62
- `hindsight: unknown bankIdTemplate placeholder "{${name}}" \u2014 valid: ` + Object.keys(resolvers).sort().map((k) => `{${k}}`).join(", ")
63
- );
64
- return "unknown";
65
- }
66
- return r();
67
- });
74
+ return applyTemplate(config.bankIdTemplate || DEFAULT_TEMPLATE, resolvers, "bankIdTemplate");
68
75
  }
69
76
 
70
77
  // src/core/config.ts
@@ -144,6 +151,12 @@ function resolveConfig(raw = {}) {
144
151
  surveyBudgetUsd: raw.surveyBudgetUsd || 2,
145
152
  surveyRefreshCommits: raw.surveyRefreshCommits ?? 20,
146
153
  gitIngest: ["message", "full", "none"].includes(raw.gitIngest) ? raw.gitIngest : "message",
154
+ // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
155
+ // nested object cannot reach the API as a tag and fail the whole retain.
156
+ retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
157
+ retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
158
+ Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
159
+ ) : {},
147
160
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
148
161
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info"
149
162
  };
@@ -197,7 +210,10 @@ var ENV_KEYS = {
197
210
  surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
198
211
  surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
199
212
  logLevel: "HINDSIGHT_LOG_LEVEL",
200
- gitIngest: "HINDSIGHT_GIT_INGEST"
213
+ gitIngest: "HINDSIGHT_GIT_INGEST",
214
+ // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
215
+ // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
216
+ retainTags: "HINDSIGHT_RETAIN_TAGS"
201
217
  };
202
218
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
203
219
  "dynamicBankId",
@@ -208,6 +224,7 @@ var ENV_BOOLEANS = /* @__PURE__ */ new Set([
208
224
  "autoSeed",
209
225
  "codebaseSurvey"
210
226
  ]);
227
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
211
228
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
212
229
  "apiPort",
213
230
  "daemonIdleTimeout",
@@ -225,6 +242,9 @@ function readEnvConfig(env = process.env) {
225
242
  if (value === void 0 || value.trim() === "") continue;
226
243
  if (ENV_BOOLEANS.has(key)) {
227
244
  out[key] = ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
245
+ } else if (ENV_LISTS.has(key)) {
246
+ const items = value.split(",").map((v) => v.trim()).filter(Boolean);
247
+ if (items.length) out[key] = items;
228
248
  } else if (ENV_NUMBERS.has(key)) {
229
249
  const n = Number(value);
230
250
  if (Number.isFinite(n)) out[key] = n;
@@ -439,11 +459,32 @@ var CODING_BANK_TEMPLATE = {
439
459
  entities_allow_free_form: true
440
460
  }
441
461
  };
462
+ var CODING_BANK_STRUCTURE = {
463
+ version: "1",
464
+ bank: {
465
+ retain_strategies: RETAIN_STRATEGIES,
466
+ entity_labels: [KNOWLEDGE_LABELS]
467
+ }
468
+ };
442
469
 
443
470
  // src/core/util.ts
444
471
  var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
472
+ function semverGte(version, min) {
473
+ const parts = (v) => {
474
+ const m = v.trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
475
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : void 0;
476
+ };
477
+ const a = version ? parts(version) : void 0;
478
+ const b = parts(min);
479
+ if (!a || !b) return false;
480
+ for (let i = 0; i < 3; i++) {
481
+ if (a[i] !== b[i]) return a[i] > b[i];
482
+ }
483
+ return true;
484
+ }
445
485
 
446
486
  // src/core/hindsight.ts
487
+ var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
447
488
  var KnowledgePagesUnavailableError = class extends Error {
448
489
  code = "knowledge_pages_unavailable";
449
490
  constructor() {
@@ -452,6 +493,7 @@ var KnowledgePagesUnavailableError = class extends Error {
452
493
  }
453
494
  };
454
495
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
496
+ var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
455
497
  var HindsightClient = class {
456
498
  apiUrl;
457
499
  apiToken;
@@ -460,6 +502,8 @@ var HindsightClient = class {
460
502
  // async operation ids collected by retain(), for drain()
461
503
  /** Tri-state capability probe: unknown until the first page request, then cached. */
462
504
  knowledgePagesSupported;
505
+ /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
506
+ idempotentRetain;
463
507
  log;
464
508
  constructor(o) {
465
509
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
@@ -488,7 +532,8 @@ var HindsightClient = class {
488
532
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
489
533
  return r;
490
534
  }
491
- /** Retain one memory. Async by default: enqueue extraction server-side and collect its op-id for drain(). */
535
+ /** Retain one memory. ALWAYS async: enqueue extraction server-side and collect its op-id for
536
+ * drain(). Nothing in this plugin can afford to block a coding agent's hook on extraction. */
492
537
  async retain(content, context, documentId, tags, strategy, opts = {}) {
493
538
  const item = {
494
539
  content,
@@ -499,14 +544,36 @@ var HindsightClient = class {
499
544
  };
500
545
  if (opts.timestamp) item.timestamp = opts.timestamp;
501
546
  if (opts.metadata) item.metadata = opts.metadata;
502
- const isAsync = opts.async !== false;
503
- const r = await this.req("POST", this.bankUrl("/memories"), { items: [item], async: isAsync });
504
- if (isAsync) {
505
- try {
506
- const j = await r.json();
507
- if (j.operation_id) this.opIds.push(j.operation_id);
508
- } catch {
509
- }
547
+ if (opts.updateMode) item.update_mode = opts.updateMode;
548
+ const body = { items: [item], async: true };
549
+ if (opts.operationId) body.operation_id = opts.operationId;
550
+ const r = await this.req("POST", this.bankUrl("/memories"), body);
551
+ try {
552
+ const j = await r.json();
553
+ if (j.operation_id) this.opIds.push(j.operation_id);
554
+ } catch {
555
+ }
556
+ }
557
+ /**
558
+ * Whether this server honours `operation_id` on an async retain, and can therefore be appended to
559
+ * safely (see MIN_IDEMPOTENT_RETAIN_VERSION). Probed once per client via GET /version; anything
560
+ * unreachable, unparseable or older answers "no", which costs efficiency, never correctness.
561
+ */
562
+ async supportsIdempotentRetain() {
563
+ if (this.idempotentRetain === void 0) {
564
+ this.idempotentRetain = await this.probeIdempotentRetain();
565
+ this.log(`server retain idempotency: ${this.idempotentRetain ? "supported" : "unavailable"}`);
566
+ }
567
+ return this.idempotentRetain;
568
+ }
569
+ async probeIdempotentRetain() {
570
+ try {
571
+ const r = await this.req("GET", `${this.apiUrl}/version`);
572
+ if (!r.ok) return false;
573
+ const j = await r.json();
574
+ return semverGte(j.api_version, MIN_IDEMPOTENT_RETAIN_VERSION);
575
+ } catch {
576
+ return false;
510
577
  }
511
578
  }
512
579
  /**
@@ -543,12 +610,39 @@ var HindsightClient = class {
543
610
  await this.req("DELETE", this.bankUrl());
544
611
  this.log(`[bank] reset ${this.bank}`);
545
612
  }
546
- await this.req("POST", this.bankUrl("/import"), CODING_BANK_TEMPLATE);
613
+ const seeded = opts.reset ? false : await this.hasBankMissions();
614
+ await this.req(
615
+ "POST",
616
+ this.bankUrl("/import"),
617
+ seeded ? CODING_BANK_STRUCTURE : CODING_BANK_TEMPLATE
618
+ );
547
619
  this.log(
548
- `[bank] template applied to ${this.bank}: missions, entity_labels {knowledge}, strategies {git, gitlog, conversation, document}`
620
+ seeded ? `[bank] structure applied to ${this.bank}: entity_labels {knowledge}, strategies {git, gitlog, conversation, document} \u2014 missions left as configured` : `[bank] template applied to ${this.bank}: missions, entity_labels {knowledge}, strategies {git, gitlog, conversation, document}`
549
621
  );
550
622
  await this.seedPages();
551
623
  }
624
+ /**
625
+ * Whether this bank already carries bank-level mission overrides — ours from an earlier seed, or
626
+ * the user's own edit. Either way they are not ours to overwrite.
627
+ *
628
+ * Reads the bank-scoped OVERRIDES, not the resolved config, so inherited global defaults don't
629
+ * read as "already set". A missing bank, or a deployment with the bank-config API switched off,
630
+ * answers false: there is nothing to preserve, and without that API a user cannot set per-bank
631
+ * missions in the first place.
632
+ */
633
+ async hasBankMissions() {
634
+ try {
635
+ const r = await this.req("GET", this.bankUrl("/config"));
636
+ if (!r.ok) return false;
637
+ const j = await r.json();
638
+ return MISSION_FIELDS.some((f) => {
639
+ const v = j.overrides?.[f];
640
+ return typeof v === "string" && v.trim() !== "";
641
+ });
642
+ } catch {
643
+ return false;
644
+ }
645
+ }
552
646
  /** Delete one document (cascades its memory units/links). Used by deepen's self-cleanup. */
553
647
  async deleteDocument(documentId) {
554
648
  await this.req("DELETE", this.bankUrl(`/documents/${encodeURIComponent(documentId)}`));
@@ -794,8 +888,7 @@ var HindsightClient = class {
794
888
  "initiative marker",
795
889
  markerId,
796
890
  ["knowledge:feature-work", `relatedPageId:${pageId}`],
797
- "document",
798
- { async: true }
891
+ "document"
799
892
  );
800
893
  return { page_id: pageId };
801
894
  }
@@ -1035,18 +1128,85 @@ async function runHook(spec, makeClient = (o) => new HindsightClient(o)) {
1035
1128
  }
1036
1129
 
1037
1130
  // src/core/retain-hook.ts
1038
- import { readFileSync as readFileSync5 } from "fs";
1131
+ import { readFileSync as readFileSync4 } from "fs";
1132
+
1133
+ // src/core/retain-cursor.ts
1134
+ import { createHash } from "crypto";
1135
+
1136
+ // src/core/uuid.ts
1137
+ import { createHash as createHash2 } from "crypto";
1039
1138
 
1040
1139
  // src/core/daemon.ts
1041
1140
  import { execFileSync as execFileSync2, spawn as realSpawn2 } from "child_process";
1042
1141
  import { dirname as dirname5, join as join6 } from "path";
1043
1142
  import { fileURLToPath as fileURLToPath2 } from "url";
1044
1143
 
1045
- // src/core/transcript.ts
1046
- import { readFileSync as readFileSync4 } from "fs";
1144
+ // src/core/retain-stamp.ts
1145
+ import { basename as basename2 } from "path";
1146
+
1147
+ // src/core/jsonl.ts
1148
+ import { closeSync, openSync, readSync, statSync } from "fs";
1149
+ import { StringDecoder } from "string_decoder";
1150
+ var CHUNK_BYTES = 64 * 1024;
1151
+ var MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024;
1152
+ function readJsonlTail(path, opts) {
1153
+ const maxBytes = opts.maxBytes ?? MAX_TRANSCRIPT_BYTES;
1154
+ let size;
1155
+ try {
1156
+ size = statSync(path).size;
1157
+ } catch {
1158
+ return { lines: emptyLines(), skippedBytes: 0 };
1159
+ }
1160
+ const skippedBytes = size > maxBytes ? size - maxBytes : 0;
1161
+ if (skippedBytes > 0) {
1162
+ log.warn(opts.scope, "transcript too large \u2014 retaining the most recent portion only", {
1163
+ path,
1164
+ sizeBytes: size,
1165
+ skippedBytes
1166
+ });
1167
+ }
1168
+ return { lines: streamLines(path, skippedBytes), skippedBytes };
1169
+ }
1170
+ function* emptyLines() {
1171
+ }
1172
+ function* streamLines(path, start) {
1173
+ let fd;
1174
+ try {
1175
+ fd = openSync(path, "r");
1176
+ } catch {
1177
+ return;
1178
+ }
1179
+ try {
1180
+ const buffer = Buffer.allocUnsafe(CHUNK_BYTES);
1181
+ const decoder = new StringDecoder("utf8");
1182
+ let pending = "";
1183
+ let position = start > 0 ? start - 1 : 0;
1184
+ let dropPartial = start > 0;
1185
+ for (; ; ) {
1186
+ const bytesRead = readSync(fd, buffer, 0, buffer.length, position);
1187
+ if (bytesRead <= 0) break;
1188
+ position += bytesRead;
1189
+ pending += decoder.write(buffer.subarray(0, bytesRead));
1190
+ let newline;
1191
+ while ((newline = pending.indexOf("\n")) !== -1) {
1192
+ const line = pending.slice(0, newline);
1193
+ pending = pending.slice(newline + 1);
1194
+ if (dropPartial) {
1195
+ dropPartial = false;
1196
+ continue;
1197
+ }
1198
+ yield line;
1199
+ }
1200
+ }
1201
+ pending += decoder.end();
1202
+ if (pending && !dropPartial) yield pending;
1203
+ } finally {
1204
+ closeSync(fd);
1205
+ }
1206
+ }
1047
1207
 
1048
1208
  // src/core/transcript-util.ts
1049
- 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;
1209
+ var MEMORY_TAG_RE = /<(hook_prompt|task-notification|system-reminder|hindsight_memory|hindsight_memories|hindsight_bank|relevant_memories|user_feedback|hindsight_knowledge|hindsight_knowledge_refresh)\b[\s\S]*?<\/\1>/g;
1050
1210
  function stripInjectedMemory(s) {
1051
1211
  return s.replace(MEMORY_TAG_RE, "");
1052
1212
  }
@@ -1081,7 +1241,7 @@ function actionLine(tool, input) {
1081
1241
  }
1082
1242
 
1083
1243
  // src/core/session-start.ts
1084
- import { readFileSync as readFileSync7 } from "fs";
1244
+ import { readFileSync as readFileSync6 } from "fs";
1085
1245
 
1086
1246
  // src/core/git.ts
1087
1247
  import { execFileSync as execFileSync3 } from "child_process";
@@ -1098,13 +1258,12 @@ import { delimiter, dirname as dirname6, join as join7 } from "path";
1098
1258
  import { fileURLToPath as fileURLToPath3 } from "url";
1099
1259
 
1100
1260
  // src/core/skill-sync.ts
1101
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync6 } from "fs";
1261
+ import { cpSync, existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
1102
1262
  import { homedir as homedir4 } from "os";
1103
1263
  import { dirname as dirname7, join as join8 } from "path";
1104
1264
  import { fileURLToPath as fileURLToPath4 } from "url";
1105
1265
 
1106
1266
  // src/core/transcript-codex.ts
1107
- import { readFileSync as readFileSync8 } from "fs";
1108
1267
  function isSyntheticUserText(text) {
1109
1268
  const s = text.trimStart();
1110
1269
  return s.startsWith("# AGENTS.md instructions for ") || s.startsWith("<environment_context>");
@@ -1113,14 +1272,8 @@ function messageText(payload) {
1113
1272
  return (payload.content || []).filter((c) => c && typeof c.text === "string").map((c) => c.text).join("\n");
1114
1273
  }
1115
1274
  function readCodexTranscript(path) {
1116
- let raw;
1117
- try {
1118
- raw = readFileSync8(path, "utf8");
1119
- } catch {
1120
- return [];
1121
- }
1122
1275
  const turns = [];
1123
- for (const rawLine of raw.split("\n")) {
1276
+ for (const rawLine of readJsonlTail(path, { scope: "codex" }).lines) {
1124
1277
  const trimmed = rawLine.trim();
1125
1278
  if (!trimmed) continue;
1126
1279
  let parsed;
@@ -1154,7 +1307,6 @@ function readCodexTranscript(path) {
1154
1307
  }
1155
1308
 
1156
1309
  // src/core/transcript-cursor.ts
1157
- import { readFileSync as readFileSync9 } from "fs";
1158
1310
  function withTimestamp(turn, timestamp) {
1159
1311
  return timestamp ? { ...turn, timestamp } : turn;
1160
1312
  }
@@ -1164,14 +1316,8 @@ function textFrom(content) {
1164
1316
  return content.filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n");
1165
1317
  }
1166
1318
  function readCursorTranscript(path) {
1167
- let raw;
1168
- try {
1169
- raw = readFileSync9(path, "utf8");
1170
- } catch {
1171
- return [];
1172
- }
1173
1319
  const turns = [];
1174
- for (const rawLine of raw.split("\n")) {
1320
+ for (const rawLine of readJsonlTail(path, { scope: "cursor-cli" }).lines) {
1175
1321
  let parsed;
1176
1322
  try {
1177
1323
  parsed = JSON.parse(rawLine);
@@ -1207,17 +1353,10 @@ function readCursorTranscript(path) {
1207
1353
  }
1208
1354
 
1209
1355
  // src/core/transcript-antigravity.ts
1210
- import { readFileSync as readFileSync10 } from "fs";
1211
1356
  function readAntigravityTranscript(path) {
1212
1357
  if (!path) return [];
1213
- let raw;
1214
- try {
1215
- raw = readFileSync10(path, "utf8");
1216
- } catch {
1217
- return [];
1218
- }
1219
1358
  const turns = [];
1220
- for (const line of raw.split("\n")) {
1359
+ for (const line of readJsonlTail(path, { scope: "antigravity-cli" }).lines) {
1221
1360
  try {
1222
1361
  const event = JSON.parse(line);
1223
1362
  const role = event.role ?? event.message?.role ?? event.type;
@@ -1238,16 +1377,9 @@ function readAntigravityTranscript(path) {
1238
1377
  }
1239
1378
 
1240
1379
  // src/core/transcript-copilot.ts
1241
- import { readFileSync as readFileSync11 } from "fs";
1242
1380
  function readCopilotTranscript(path) {
1243
- let raw;
1244
- try {
1245
- raw = readFileSync11(path, "utf8");
1246
- } catch {
1247
- return [];
1248
- }
1249
1381
  const turns = [];
1250
- for (const rawLine of raw.split("\n")) {
1382
+ for (const rawLine of readJsonlTail(path, { scope: "copilot-cli" }).lines) {
1251
1383
  try {
1252
1384
  const event = JSON.parse(rawLine);
1253
1385
  const role = event.type === "user.message" ? "user" : event.type === "assistant.message" ? "assistant" : void 0;
@@ -1261,7 +1393,7 @@ function readCopilotTranscript(path) {
1261
1393
  }
1262
1394
 
1263
1395
  // src/core/transcript-grok.ts
1264
- import { existsSync as existsSync4, readFileSync as readFileSync12, readdirSync } from "fs";
1396
+ import { existsSync as existsSync4, readFileSync as readFileSync7, readdirSync } from "fs";
1265
1397
  import { homedir as homedir5 } from "os";
1266
1398
  import { join as join9 } from "path";
1267
1399
  var CHAT_HISTORY = "chat_history.jsonl";
@@ -1272,7 +1404,7 @@ function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME ||
1272
1404
  try {
1273
1405
  for (const candidate of readdirSync(sessionsDir)) {
1274
1406
  const directory = join9(sessionsDir, candidate);
1275
- if (readFileSync12(join9(directory, ".cwd"), "utf8").trim() === cwd) {
1407
+ if (readFileSync7(join9(directory, ".cwd"), "utf8").trim() === cwd) {
1276
1408
  return join9(directory, sessionId, CHAT_HISTORY);
1277
1409
  }
1278
1410
  }
@@ -1281,14 +1413,8 @@ function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME ||
1281
1413
  return direct;
1282
1414
  }
1283
1415
  function readGrokTranscript(path) {
1284
- let raw;
1285
- try {
1286
- raw = readFileSync12(path, "utf8");
1287
- } catch {
1288
- return [];
1289
- }
1290
1416
  const turns = [];
1291
- for (const rawLine of raw.split("\n")) {
1417
+ for (const rawLine of readJsonlTail(path, { scope: "grok-build" }).lines) {
1292
1418
  try {
1293
1419
  const event = JSON.parse(rawLine);
1294
1420
  if (event.type !== "user" && event.type !== "assistant") continue;