@vectorize-io/hindsight-coding-agents 0.2.1 → 0.3.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.
@@ -4406,11 +4406,11 @@ var require_core = __commonJS({
4406
4406
  Ajv2.ValidationError = validation_error_1.default;
4407
4407
  Ajv2.MissingRefError = ref_error_1.default;
4408
4408
  exports.default = Ajv2;
4409
- function checkOptions(checkOpts, options, msg, log = "error") {
4409
+ function checkOptions(checkOpts, options, msg, log2 = "error") {
4410
4410
  for (const key in checkOpts) {
4411
4411
  const opt = key;
4412
4412
  if (opt in options)
4413
- this.logger[log](`${msg}: option ${key}. ${checkOpts[opt]}`);
4413
+ this.logger[log2](`${msg}: option ${key}. ${checkOpts[opt]}`);
4414
4414
  }
4415
4415
  }
4416
4416
  function getSchEnv(keyRef) {
@@ -30997,7 +30997,7 @@ function resolveConfig(raw = {}) {
30997
30997
  disabled: raw.disabled ?? false,
30998
30998
  retainSessions: raw.retainSessions ?? true,
30999
30999
  // opencode: write back by default (parity with hook-harness Stop)
31000
- retainEveryTurns: raw.retainEveryTurns || 1,
31000
+ maxParallelRetains: raw.maxParallelRetains || 10,
31001
31001
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
31002
31002
  autoReflect: raw.autoReflect ?? true,
31003
31003
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
@@ -31056,7 +31056,7 @@ var ENV_KEYS = {
31056
31056
  harness: "HINDSIGHT_HARNESS",
31057
31057
  disabled: "HINDSIGHT_DISABLED",
31058
31058
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
31059
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
31059
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
31060
31060
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
31061
31061
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
31062
31062
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
@@ -31085,7 +31085,7 @@ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
31085
31085
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
31086
31086
  "apiPort",
31087
31087
  "daemonIdleTimeout",
31088
- "retainEveryTurns",
31088
+ "maxParallelRetains",
31089
31089
  "reflectTimeoutMs",
31090
31090
  "pageRefreshEveryTurns",
31091
31091
  "seedLimit",
@@ -31149,6 +31149,7 @@ function resolvePartial(cfg, patch) {
31149
31149
 
31150
31150
  // src/core/bank.ts
31151
31151
  import { execFileSync } from "child_process";
31152
+ import { existsSync } from "fs";
31152
31153
  import { homedir as homedir2 } from "os";
31153
31154
  import { basename, dirname as dirname2, join as join3, normalize, sep } from "path";
31154
31155
 
@@ -31187,12 +31188,32 @@ function getProjectRootFromGit(directory) {
31187
31188
  function projectNameOf(directory) {
31188
31189
  return gitProjectName(directory, true);
31189
31190
  }
31191
+ var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
31192
+ function nearestExistingDir(directory) {
31193
+ let current2 = directory;
31194
+ while (current2) {
31195
+ if (existsSync(current2)) return current2;
31196
+ const parent = dirname2(current2);
31197
+ if (parent === current2) return "";
31198
+ current2 = parent;
31199
+ }
31200
+ return "";
31201
+ }
31202
+ function dirName(directory) {
31203
+ return directory && basename(directory) || "unknown";
31204
+ }
31190
31205
  function gitProjectName(directory, resolveWorktrees) {
31191
31206
  if (resolveWorktrees) {
31192
- const root = getProjectRootFromGit(directory);
31193
- if (root) return basename(root);
31207
+ const candidates = [
31208
+ nearestExistingDir(directory),
31209
+ ...PROJECT_ROOT_ENV.map((v) => process.env[v] || "")
31210
+ ];
31211
+ for (const candidate of candidates) {
31212
+ const root = candidate ? getProjectRootFromGit(candidate) : null;
31213
+ if (root) return basename(root);
31214
+ }
31194
31215
  }
31195
- return directory ? basename(directory) : "unknown";
31216
+ return dirName(directory);
31196
31217
  }
31197
31218
  function mapLookup(map2, directory) {
31198
31219
  const cwd = normalize(directory);
@@ -31213,7 +31234,7 @@ function deriveBankId(config2, directory, harness = "coding") {
31213
31234
  if (!dynamic) return config2.bankId || DEFAULT_BANK_NAME;
31214
31235
  const resolvers = {
31215
31236
  harness: () => harness,
31216
- project: () => directory ? basename(directory) : "unknown",
31237
+ project: () => dirName(directory),
31217
31238
  gitProject: () => gitProjectName(directory, config2.resolveWorktrees ?? true),
31218
31239
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
31219
31240
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -31365,9 +31386,40 @@ function semverGte(version2, min) {
31365
31386
  }
31366
31387
  return true;
31367
31388
  }
31389
+ async function pool(items, n, fn, onError, onProgress) {
31390
+ let i = 0, done = 0;
31391
+ async function worker() {
31392
+ while (i < items.length) {
31393
+ const idx = i++;
31394
+ try {
31395
+ await fn(items[idx], idx);
31396
+ } catch (e) {
31397
+ onError?.(idx, e);
31398
+ }
31399
+ onProgress?.(++done, items.length);
31400
+ }
31401
+ }
31402
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
31403
+ }
31368
31404
 
31369
31405
  // src/core/hindsight.ts
31370
31406
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
31407
+ var RateLimitedError = class extends Error {
31408
+ constructor(retryAfterMs2) {
31409
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
31410
+ this.retryAfterMs = retryAfterMs2;
31411
+ this.name = "RateLimitedError";
31412
+ }
31413
+ retryAfterMs;
31414
+ code = "rate_limited";
31415
+ };
31416
+ function retryAfterMs(header) {
31417
+ if (!header) return 0;
31418
+ const secs = Number(header.trim());
31419
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
31420
+ const at = Date.parse(header);
31421
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
31422
+ }
31371
31423
  var KnowledgePagesUnavailableError = class extends Error {
31372
31424
  code = "knowledge_pages_unavailable";
31373
31425
  constructor() {
@@ -31376,6 +31428,10 @@ var KnowledgePagesUnavailableError = class extends Error {
31376
31428
  }
31377
31429
  };
31378
31430
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
31431
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
31432
+ var POLL_CYCLE_MS = 5e3;
31433
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
31434
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
31379
31435
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
31380
31436
  var HindsightClient = class {
31381
31437
  apiUrl;
@@ -31388,12 +31444,14 @@ var HindsightClient = class {
31388
31444
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
31389
31445
  idempotentRetain;
31390
31446
  log;
31447
+ maxParallelRetains;
31391
31448
  constructor(o) {
31392
31449
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
31393
31450
  this.apiToken = o.apiToken;
31394
31451
  this.bank = o.bank;
31395
31452
  this.log = o.log ?? (() => {
31396
31453
  });
31454
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
31397
31455
  }
31398
31456
  headers() {
31399
31457
  const h = { "Content-Type": "application/json" };
@@ -31411,6 +31469,8 @@ var HindsightClient = class {
31411
31469
  body: body ? JSON.stringify(body) : void 0,
31412
31470
  signal: AbortSignal.timeout(15e3)
31413
31471
  });
31472
+ if (r.status === 429 && !tolerate.includes(429))
31473
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
31414
31474
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
31415
31475
  throw new Error(`${method} ${url2} -> ${r.status} ${await r.text()}`);
31416
31476
  return r;
@@ -31542,7 +31602,14 @@ var HindsightClient = class {
31542
31602
  return 0;
31543
31603
  }
31544
31604
  }
31545
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
31605
+ /**
31606
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
31607
+ *
31608
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
31609
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
31610
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
31611
+ * of hammering the next cycle 5s later.
31612
+ */
31546
31613
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
31547
31614
  if (!ids.length) return;
31548
31615
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -31550,23 +31617,29 @@ var HindsightClient = class {
31550
31617
  const pending = new Set(ids);
31551
31618
  let failed = 0;
31552
31619
  while (pending.size && Date.now() - start < maxMs) {
31553
- await Promise.all(
31554
- [...pending].map(async (id) => {
31555
- try {
31556
- const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
31557
- if (!r.ok) return;
31558
- const st = ((await r.json()).status || "").toLowerCase();
31559
- if (TERMINAL.has(st)) {
31560
- pending.delete(id);
31561
- if (st !== "completed") failed++;
31562
- }
31563
- } catch {
31620
+ let backoffMs = POLL_CYCLE_MS;
31621
+ await pool([...pending], this.maxParallelRetains, async (id) => {
31622
+ try {
31623
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
31624
+ if (r.status === 429) {
31625
+ backoffMs = Math.min(
31626
+ RETRY_AFTER_CEILING_MS,
31627
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
31628
+ );
31629
+ return;
31564
31630
  }
31565
- })
31566
- );
31631
+ if (!r.ok) return;
31632
+ const st = ((await r.json()).status || "").toLowerCase();
31633
+ if (TERMINAL.has(st)) {
31634
+ pending.delete(id);
31635
+ if (st !== "completed") failed++;
31636
+ }
31637
+ } catch {
31638
+ }
31639
+ });
31567
31640
  if (pending.size) {
31568
31641
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
31569
- await sleep(5e3);
31642
+ await sleep(backoffMs);
31570
31643
  }
31571
31644
  }
31572
31645
  this.log(
@@ -31766,13 +31839,20 @@ var HindsightClient = class {
31766
31839
  const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
31767
31840
  const content = `${verb}: ${args.title}. ${args.summary}`;
31768
31841
  const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
31769
- await this.retain(
31770
- content,
31771
- "initiative marker",
31772
- markerId,
31773
- ["knowledge:feature-work", `relatedPageId:${pageId}`],
31774
- "document"
31775
- );
31842
+ const tags = [
31843
+ .../* @__PURE__ */ new Set([
31844
+ ...args.stamp?.tags ?? [],
31845
+ "knowledge:feature-work",
31846
+ `relatedPageId:${pageId}`
31847
+ ])
31848
+ ];
31849
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
31850
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
31851
+ metadata: args.stamp?.metadata
31852
+ });
31853
+ } else {
31854
+ await this.retain(content, "initiative marker", markerId, tags, "document");
31855
+ }
31776
31856
  return { page_id: pageId };
31777
31857
  }
31778
31858
  /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
@@ -31795,7 +31875,7 @@ var HindsightClient = class {
31795
31875
  };
31796
31876
 
31797
31877
  // src/core/knowledge-tools.ts
31798
- import { existsSync as existsSync2 } from "fs";
31878
+ import { existsSync as existsSync3 } from "fs";
31799
31879
  import { homedir as homedir4 } from "os";
31800
31880
  import { join as join5 } from "path";
31801
31881
 
@@ -31835,7 +31915,7 @@ function parsePageList(raw) {
31835
31915
 
31836
31916
  // src/core/survey.ts
31837
31917
  import { spawn as realSpawn2 } from "child_process";
31838
- import { accessSync, constants, existsSync } from "fs";
31918
+ import { accessSync, constants, existsSync as existsSync2 } from "fs";
31839
31919
  import { homedir as homedir3 } from "os";
31840
31920
  import { delimiter, dirname as dirname3, join as join4 } from "path";
31841
31921
  import { fileURLToPath as fileURLToPath2 } from "url";
@@ -31950,7 +32030,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
31950
32030
  workspace: opts.repoDir ?? process.cwd(),
31951
32031
  config: {
31952
32032
  path: configPath,
31953
- exists: existsSync2(configPath),
32033
+ exists: existsSync3(configPath),
31954
32034
  api_url: cfg.apiUrl,
31955
32035
  api_token_configured: Boolean(cfg.apiToken),
31956
32036
  disabled: cfg.disabled
@@ -32015,7 +32095,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
32015
32095
  relates_to_page_id: external_exports.string().optional()
32016
32096
  },
32017
32097
  handler: guarded(
32018
- async ({ title, summary, relates_to_page_id }) => client.captureInitiative({ title, summary, relatesToPageId: relates_to_page_id })
32098
+ async ({ title, summary, relates_to_page_id }) => client.captureInitiative({
32099
+ title,
32100
+ summary,
32101
+ relatesToPageId: relates_to_page_id,
32102
+ ...opts.stampFor ? { stamp: opts.stampFor() } : {}
32103
+ })
32019
32104
  )
32020
32105
  },
32021
32106
  {
@@ -32024,13 +32109,24 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
32024
32109
  inputSchema: { title: external_exports.string(), content: external_exports.string() },
32025
32110
  handler: guarded(async ({ title, content }) => {
32026
32111
  const docId = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "doc";
32112
+ const stamp = opts.stampFor?.();
32113
+ const metadata = {
32114
+ ...stamp?.metadata,
32115
+ ...opts.harness ? { harness: opts.harness } : {}
32116
+ };
32027
32117
  await client.retain(
32028
32118
  content,
32029
32119
  "ingested document",
32030
32120
  docId,
32031
- ["source:upload", ...opts.harness ? [`harness:${opts.harness}`] : []],
32121
+ [
32122
+ .../* @__PURE__ */ new Set([
32123
+ ...stamp?.tags ?? [],
32124
+ "source:upload",
32125
+ ...opts.harness ? [`harness:${opts.harness}`] : []
32126
+ ])
32127
+ ],
32032
32128
  "document",
32033
- { metadata: opts.harness ? { harness: opts.harness } : void 0 }
32129
+ Object.keys(metadata).length ? { metadata } : {}
32034
32130
  );
32035
32131
  return { ok: true, doc_id: docId };
32036
32132
  })
@@ -32038,18 +32134,106 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
32038
32134
  ];
32039
32135
  }
32040
32136
 
32137
+ // src/core/log.ts
32138
+ import { appendFileSync, mkdirSync } from "fs";
32139
+ import { tmpdir } from "os";
32140
+ import { dirname as dirname4, join as join6 } from "path";
32141
+ var WEIGHT = { debug: 10, info: 20, warn: 30, error: 40 };
32142
+ var current = ["debug", "info", "warn", "error"].find(
32143
+ (l) => l === process.env.HINDSIGHT_LOG_LEVEL
32144
+ ) ?? "info";
32145
+ function logFilePath() {
32146
+ return process.env.HINDSIGHT_LOG_FILE || join6(tmpdir(), "hindsight-coding-agent", "plugin.log");
32147
+ }
32148
+ function write(level, scope, msg, extra) {
32149
+ if (WEIGHT[level] < WEIGHT[current]) return;
32150
+ try {
32151
+ const file2 = logFilePath();
32152
+ mkdirSync(dirname4(file2), { recursive: true });
32153
+ appendFileSync(
32154
+ file2,
32155
+ `${(/* @__PURE__ */ new Date()).toISOString()} ${level.toUpperCase().padEnd(5)} [${scope}] ${msg}` + (extra && Object.keys(extra).length ? ` ${JSON.stringify(extra)}` : "") + "\n"
32156
+ );
32157
+ } catch {
32158
+ }
32159
+ }
32160
+ var log = {
32161
+ debug: (scope, msg, extra) => write("debug", scope, msg, extra),
32162
+ info: (scope, msg, extra) => write("info", scope, msg, extra),
32163
+ warn: (scope, msg, extra) => write("warn", scope, msg, extra),
32164
+ error: (scope, msg, extra) => write("error", scope, msg, extra)
32165
+ };
32166
+
32167
+ // src/core/retain-stamp.ts
32168
+ import { basename as basename2 } from "path";
32169
+ var RESERVED_TAG_PREFIX = /^(source|harness):/;
32170
+ function resolversFor(ctx) {
32171
+ return {
32172
+ // Worktree-aware like the bank id, so every linked worktree of a repo stamps the SAME name —
32173
+ // otherwise a shared bank ends up with `project:app` and `project:app-wt2` for one repository.
32174
+ gitProject: () => projectNameOf(ctx.directory),
32175
+ project: () => ctx.directory ? basename2(ctx.directory) : "unknown",
32176
+ harness: () => ctx.harness,
32177
+ bankId: () => ctx.bankId,
32178
+ sessionId: () => ctx.sessionId ?? "unknown",
32179
+ timestamp: () => (/* @__PURE__ */ new Date()).toISOString(),
32180
+ channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
32181
+ user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
32182
+ };
32183
+ }
32184
+ function buildRetainStamp(cfg, ctx) {
32185
+ const hasTags = Boolean(cfg.retainTags?.length);
32186
+ const hasMetadata = Boolean(cfg.retainMetadata && Object.keys(cfg.retainMetadata).length);
32187
+ if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
32188
+ const base = resolversFor(ctx);
32189
+ const cache = /* @__PURE__ */ new Map();
32190
+ const resolvers = Object.fromEntries(
32191
+ Object.entries(base).map(([name, resolve2]) => [
32192
+ name,
32193
+ () => {
32194
+ const hit = cache.get(name);
32195
+ if (hit !== void 0) return hit;
32196
+ const value = resolve2();
32197
+ cache.set(name, value);
32198
+ return value;
32199
+ }
32200
+ ])
32201
+ );
32202
+ const tags = (cfg.retainTags ?? []).map((t) => applyTemplate(t, resolvers, "retainTags").trim()).filter(Boolean).filter((t) => {
32203
+ if (!RESERVED_TAG_PREFIX.test(t)) return true;
32204
+ log.warn("retain-stamp", "ignoring reserved retainTags entry", { tag: t });
32205
+ return false;
32206
+ });
32207
+ const metadata = {};
32208
+ for (const [key, value] of Object.entries(cfg.retainMetadata ?? {})) {
32209
+ metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
32210
+ }
32211
+ return { tags, metadata };
32212
+ }
32213
+
32041
32214
  // src/mcp-server.ts
32042
- function selectTools(cfg, client, bankId) {
32043
- return cfg.disabled ? [] : buildKnowledgeTools(client, bankId, { repoDir: process.cwd(), harness: cfg.harness });
32215
+ function selectTools(cfg, client, bankId, opts = {}) {
32216
+ const cwd = opts.cwd ?? process.cwd();
32217
+ const harness = opts.harness ?? cfg.harness;
32218
+ return cfg.disabled ? [] : buildKnowledgeTools(client, bankId, {
32219
+ repoDir: cwd,
32220
+ harness,
32221
+ stampFor: () => buildRetainStamp(cfg, { directory: cwd, harness, bankId })
32222
+ });
32044
32223
  }
32045
32224
  async function main() {
32046
32225
  const cwd = process.env.HINDSIGHT_MCP_PROJECT_CWD || process.cwd();
32047
32226
  const harness = process.env.HINDSIGHT_MCP_HARNESS || "claude-code";
32048
32227
  const cfg0 = loadConfig({ harness });
32049
32228
  const { cfg, bankId } = applyBankConfig(cfg0, deriveBankId(cfg0, cwd, harness));
32050
- const client = new HindsightClient({ apiUrl: cfg.apiUrl, apiToken: cfg.apiToken, bank: bankId });
32229
+ const client = new HindsightClient({
32230
+ apiUrl: cfg.apiUrl,
32231
+ apiToken: cfg.apiToken,
32232
+ bank: bankId,
32233
+ maxParallelRetains: cfg.maxParallelRetains
32234
+ });
32051
32235
  const server = new McpServer({ name: "hindsight", version: "0.1.0" });
32052
- for (const t of selectTools(cfg, client, bankId)) {
32236
+ for (const t of selectTools(cfg, client, bankId, { cwd, harness })) {
32053
32237
  server.tool(t.name, t.description, t.inputSchema, t.handler);
32054
32238
  }
32055
32239
  await server.connect(new StdioServerTransport());