@vectorize-io/hindsight-coding-agents 0.7.0 → 0.8.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.
Files changed (56) hide show
  1. package/README.md +137 -13
  2. package/dist/antigravity-hook.js +711 -55
  3. package/dist/antigravity-statusline.js +68 -7
  4. package/dist/antigravity-stop-hook.js +771 -57
  5. package/dist/claude-hook.js +711 -55
  6. package/dist/claude-sessionstart-hook.js +789 -68
  7. package/dist/claude-stop-hook.js +771 -57
  8. package/dist/cline.js +295 -75
  9. package/dist/codex-hook.js +711 -55
  10. package/dist/codex-sessionstart-hook.js +789 -68
  11. package/dist/codex-stop-hook.js +771 -57
  12. package/dist/copilot-hook.js +711 -55
  13. package/dist/copilot-sessionstart-hook.js +789 -68
  14. package/dist/copilot-stop-hook.js +771 -57
  15. package/dist/cursor-hook.js +711 -55
  16. package/dist/cursor-sessionstart-hook.js +789 -68
  17. package/dist/cursor-stop-hook.js +771 -57
  18. package/dist/daemon-start.js +38 -1
  19. package/dist/dcode-hook.js +711 -55
  20. package/dist/dcode-sessionstart-hook.js +789 -68
  21. package/dist/dcode-stop-hook.js +771 -57
  22. package/dist/deepen.js +236 -61
  23. package/dist/devin-hook.js +711 -55
  24. package/dist/devin-sessionstart-hook.js +789 -68
  25. package/dist/devin-stop-hook.js +771 -57
  26. package/dist/droid-hook.js +711 -55
  27. package/dist/droid-sessionstart-hook.js +789 -68
  28. package/dist/droid-stop-hook.js +771 -57
  29. package/dist/dsh.js +296 -76
  30. package/dist/grok-hook.js +711 -55
  31. package/dist/grok-sessionstart-hook.js +789 -68
  32. package/dist/grok-stop-hook.js +771 -57
  33. package/dist/hindsight-seed.js +41 -4
  34. package/dist/index.js +295 -75
  35. package/dist/installer.js +1148 -303
  36. package/dist/kilo.js +295 -75
  37. package/dist/kimi-hook.js +3909 -0
  38. package/dist/kimi-sessionstart-hook.js +4650 -0
  39. package/dist/kimi-stop-hook.js +4218 -0
  40. package/dist/mcp-server.js +162 -33
  41. package/dist/opencode2.js +298 -76
  42. package/dist/pi.js +299 -75
  43. package/dist/prime-agent.js +299 -75
  44. package/dist/qwen-hook.js +711 -55
  45. package/dist/qwen-sessionstart-hook.js +789 -68
  46. package/dist/qwen-stop-hook.js +771 -57
  47. package/dist/status.js +132 -14
  48. package/dist/traecode-hook.js +3909 -0
  49. package/dist/traecode-sessionstart-hook.js +4650 -0
  50. package/dist/traecode-stop-hook.js +4218 -0
  51. package/dist/zcode-hook.js +711 -55
  52. package/dist/zcode-sessionstart-hook.js +789 -68
  53. package/dist/zcode-stop-hook.js +771 -57
  54. package/package.json +15 -11
  55. package/plugin.json +1 -1
  56. package/skill/SKILL.md +70 -11
package/dist/pi.js CHANGED
@@ -14823,13 +14823,13 @@ function isWithin(directory, configured) {
14823
14823
  function mapLookup(map2, directory) {
14824
14824
  const cwd = normalize(directory);
14825
14825
  let best;
14826
- for (const [dir, bank] of Object.entries(map2)) {
14826
+ for (const [dir, value] of Object.entries(map2)) {
14827
14827
  const p = configuredDir(dir);
14828
14828
  if (isWithin(cwd, p)) {
14829
- if (!best || p.length > best.len) best = { len: p.length, bank };
14829
+ if (!best || p.length > best.len) best = { len: p.length, value };
14830
14830
  }
14831
14831
  }
14832
- return best?.bank;
14832
+ return best?.value;
14833
14833
  }
14834
14834
  function lookupDirectories(config2, directory, sessionRoot = "") {
14835
14835
  const directories = [normalize(directory)];
@@ -14853,6 +14853,10 @@ function isOptedIn(config2, directory) {
14853
14853
  const pathMap = config2.mapPathToBank;
14854
14854
  return Boolean(pathMap && directories.some((candidate) => mapLookup(pathMap, candidate)));
14855
14855
  }
14856
+ function pathSection(config2, paths, directory) {
14857
+ if (!directory || !paths) return void 0;
14858
+ return lookupDirectories(config2, directory).map((candidate) => mapLookup(paths, candidate)).find((section) => section !== void 0);
14859
+ }
14856
14860
  function mappedBank(config2, directory, sessionRoot) {
14857
14861
  const pathMap = config2.mapPathToBank;
14858
14862
  if (!directory || !pathMap) return void 0;
@@ -15100,12 +15104,17 @@ var CODING_BANK_TEMPLATE = {
15100
15104
  }
15101
15105
  };
15102
15106
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
15107
+ var PLUGIN_GOVERNED_BANK_FIELDS = [
15108
+ "retain_strategies",
15109
+ "entity_labels",
15110
+ "retain_extraction_mode"
15111
+ ];
15103
15112
  function isSet(v) {
15104
15113
  if (v === null || v === void 0) return false;
15105
15114
  if (typeof v === "string") return v.trim() !== "";
15106
15115
  return true;
15107
15116
  }
15108
- function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
15117
+ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE, defaults = {}) {
15109
15118
  const current2 = overrides ?? {};
15110
15119
  const template = CODING_BANK_TEMPLATE.bank;
15111
15120
  const bank = {};
@@ -15134,6 +15143,10 @@ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
15134
15143
  const [knowledgeGroup] = template.entity_labels;
15135
15144
  if (!labels.some((g) => g?.key === knowledgeGroup.key))
15136
15145
  bank.entity_labels = [...labels, knowledgeGroup];
15146
+ for (const [key, value] of Object.entries(defaults)) {
15147
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key) || !isSet(value) || isSet(current2[key])) continue;
15148
+ bank[key] = value;
15149
+ }
15137
15150
  return Object.keys(bank).length > 0 ? { version: "1", bank } : void 0;
15138
15151
  }
15139
15152
 
@@ -15256,6 +15269,18 @@ var DEFAULT_RECALL_OPTIONS = {
15256
15269
  var POLL_CYCLE_MS = 5e3;
15257
15270
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
15258
15271
  var RETRY_AFTER_CEILING_MS = 60 * 1e3;
15272
+ function shapePage(page) {
15273
+ const p = page ?? {};
15274
+ const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
15275
+ return {
15276
+ id: p.id,
15277
+ name: p.name,
15278
+ ...p.description ? { description: p.description } : {},
15279
+ ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
15280
+ ...p.timestamp ? { last_updated_at: p.timestamp } : {},
15281
+ body
15282
+ };
15283
+ }
15259
15284
  var HindsightClient = class {
15260
15285
  apiUrl;
15261
15286
  /** The credential the NEXT request will sign with — NOT the one the config file holds. The two
@@ -15293,7 +15318,10 @@ var HindsightClient = class {
15293
15318
  return this.token;
15294
15319
  }
15295
15320
  headers() {
15296
- const h = { "Content-Type": "application/json" };
15321
+ const h = {
15322
+ "Content-Type": "application/json",
15323
+ "Accept-Encoding": "identity"
15324
+ };
15297
15325
  if (this.token) h["Authorization"] = `Bearer ${this.token}`;
15298
15326
  return h;
15299
15327
  }
@@ -15401,6 +15429,23 @@ var HindsightClient = class {
15401
15429
  return false;
15402
15430
  }
15403
15431
  }
15432
+ /**
15433
+ * Whether a session write-back may use `update_mode="append"`: the server must dedupe by
15434
+ * `operation_id` AND the bank must keep document text, or the server rejects the append in the
15435
+ * background (#4613). Only an explicit `store_document_text: false` answers "no" — an unreachable
15436
+ * or unparseable config assumes the default (stored), so a flaky probe never downgrades appends.
15437
+ */
15438
+ async supportsAppendRetain() {
15439
+ if (!await this.supportsIdempotentRetain()) return false;
15440
+ try {
15441
+ const r = await this.req("GET", this.bankUrl("/config"));
15442
+ if (!r.ok) return true;
15443
+ const j = await r.json();
15444
+ return j.config?.store_document_text !== false;
15445
+ } catch {
15446
+ return true;
15447
+ }
15448
+ }
15404
15449
  /**
15405
15450
  * Every document_id currently in the bank under a strategy tag (e.g. `source:git`), paginated into a
15406
15451
  * Set. Powers the incremental git-sync's "what's already ingested?" check — since git commits are stored
@@ -15426,6 +15471,24 @@ var HindsightClient = class {
15426
15471
  }
15427
15472
  return ids;
15428
15473
  }
15474
+ /**
15475
+ * The tags on one document, or undefined when the bank holds none with that id. Read from the
15476
+ * document LISTING narrowed by `q` (a substring match on the id, so the exact id is picked out of
15477
+ * the page) rather than GET /documents/{id}, which also sends the document's full text: the
15478
+ * caller, the git-log freshness check on SessionStart, reads a ~100k-character document for one tag.
15479
+ */
15480
+ async documentTags(documentId) {
15481
+ const limit = 100;
15482
+ for (let offset = 0; ; offset += limit) {
15483
+ const q = `?q=${encodeURIComponent(documentId)}&limit=${limit}&offset=${offset}`;
15484
+ const r = await this.req("GET", this.bankUrl(`/documents${q}`));
15485
+ const j = await r.json();
15486
+ const items = j.items ?? [];
15487
+ const hit = items.find((it) => it.id === documentId);
15488
+ if (hit) return hit.tags ?? [];
15489
+ if (items.length < limit || offset + limit >= (j.total ?? 0)) return void 0;
15490
+ }
15491
+ }
15429
15492
  /** Configure the bank: POST the coding bank manifest to /import (missions, retain strategies,
15430
15493
  * entity labels), then seed knowledge pages when the server supports them. Both halves are
15431
15494
  * idempotent and ADDITIVE — nothing the bank already says is overwritten (#3927), bar the
@@ -15447,7 +15510,8 @@ var HindsightClient = class {
15447
15510
  } else {
15448
15511
  const manifest = codingBankManifest(
15449
15512
  opts.reset ? void 0 : await this.readBankOverrides(),
15450
- opts.extractionMode
15513
+ opts.extractionMode,
15514
+ opts.defaults
15451
15515
  );
15452
15516
  if (!manifest) {
15453
15517
  this.log(`[bank] ${this.bank} already carries the coding structure \u2014 nothing to apply`);
@@ -15653,8 +15717,8 @@ var HindsightClient = class {
15653
15717
  return { items };
15654
15718
  }
15655
15719
  /**
15656
- * Read one knowledge page's synthesized content by knowledge-base id, as an OKF document
15657
- * (YAML frontmatter + markdown body). The endpoint omits the internal reflect trace that built
15720
+ * Read one knowledge page's synthesized content by knowledge-base id, shaped by `shapePage` so
15721
+ * the body arrives once. The endpoint omits the internal reflect trace that built
15658
15722
  * the page — that is 70-95% of the raw bytes and can blow past an MCP host's per-tool-result
15659
15723
  * token cap.
15660
15724
  */
@@ -15665,7 +15729,7 @@ var HindsightClient = class {
15665
15729
  this.bankUrl(`/knowledge-base/pages/${encodeURIComponent(pageId)}`)
15666
15730
  );
15667
15731
  if (r.status === 404) throw new Error(`knowledge page not found: ${pageId}`);
15668
- return await r.json();
15732
+ return shapePage(await r.json());
15669
15733
  }
15670
15734
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
15671
15735
  * Returns page-level hits with a relevance snippet — the real search behind
@@ -15686,6 +15750,7 @@ var HindsightClient = class {
15686
15750
  return (j.results ?? []).map((x) => ({
15687
15751
  id: x.id,
15688
15752
  name: x.name,
15753
+ ...x.source_query ? { source_query: x.source_query } : {},
15689
15754
  snippet: x.snippet ?? "",
15690
15755
  score: x.score ?? 0
15691
15756
  }));
@@ -15956,6 +16021,7 @@ function resolveCustomPages(raw) {
15956
16021
  }
15957
16022
  var DEFAULT_REFLECT_TIMEOUT_MS = 2e4;
15958
16023
  var DEFAULT_REFLECT_TOOL_TIMEOUT_MS = 33e4;
16024
+ var DEFAULT_INJECT_TIMEOUT_MS = 7e3;
15959
16025
  var REFLECT_BUDGETS = ["low", "mid", "high"];
15960
16026
  function resolveReflectBudget(raw) {
15961
16027
  const value = raw.reflectBudget;
@@ -15982,6 +16048,22 @@ function resolveObservationScopes(raw) {
15982
16048
  }
15983
16049
  return DEFAULT_OBSERVATION_SCOPES;
15984
16050
  }
16051
+ function resolveDefaultBankConfig(raw) {
16052
+ const value = raw;
16053
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
16054
+ const out = {};
16055
+ for (const [key, v] of Object.entries(value)) {
16056
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key)) {
16057
+ log.warn(
16058
+ "config",
16059
+ `ignoring defaultBankConfig.${key} \u2014 the plugin manages this field itself` + (key === "retain_extraction_mode" ? " (set retainExtractionMode instead)" : "")
16060
+ );
16061
+ continue;
16062
+ }
16063
+ out[key] = v;
16064
+ }
16065
+ return out;
16066
+ }
15985
16067
  var AUTO_INJECT_MODES = ["reflect", "pages", "recall", "none"];
15986
16068
  function resolveAutoInject(raw) {
15987
16069
  if (raw.autoReflect !== void 0) {
@@ -16021,18 +16103,21 @@ function resolveConfig(raw = {}) {
16021
16103
  // write sessions back by default, every harness
16022
16104
  manageBankConfig: raw.manageBankConfig ?? true,
16023
16105
  retainExtractionMode: RETAIN_EXTRACTION_MODES.includes(raw.retainExtractionMode) ? raw.retainExtractionMode : DEFAULT_RETAIN_EXTRACTION_MODE,
16106
+ defaultBankConfig: resolveDefaultBankConfig(raw.defaultBankConfig),
16024
16107
  maxParallelRetains: raw.maxParallelRetains || 10,
16025
16108
  reflectTimeoutMs: raw.reflectTimeoutMs || DEFAULT_REFLECT_TIMEOUT_MS,
16026
16109
  // Inherit an explicitly-raised reflectTimeoutMs (that is what users reaching for a longer
16027
16110
  // reflect already set), but never let it LOWER the tool below the default — a short window is
16028
16111
  // set to bound the automatic hook, not to cut off a call the agent is waiting on.
16029
16112
  reflectToolTimeoutMs: raw.reflectToolTimeoutMs || Math.max(raw.reflectTimeoutMs || 0, DEFAULT_REFLECT_TOOL_TIMEOUT_MS),
16113
+ injectTimeoutMs: raw.injectTimeoutMs || DEFAULT_INJECT_TIMEOUT_MS,
16030
16114
  reflectBudget: resolveReflectBudget(raw),
16031
16115
  autoInject: resolveAutoInject(raw),
16032
16116
  pageSearchLimit: raw.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT,
16033
16117
  // Same shape as retainMetadata: an object, or nothing. An array would spread into numeric
16034
16118
  // keys and reach the API as garbage, so it is rejected like any other non-object.
16035
16119
  recallOptions: raw.recallOptions && typeof raw.recallOptions === "object" && !Array.isArray(raw.recallOptions) ? { ...raw.recallOptions } : {},
16120
+ toolGuideExtra: typeof raw.toolGuideExtra === "string" && raw.toolGuideExtra.trim() ? raw.toolGuideExtra : void 0,
16036
16121
  // Every turn, not every tenth. The guide is what tells the agent WHEN to reach for memory, and
16037
16122
  // at a cadence of 10 a normal session is told once, on turn 1, and never again. Measured over
16038
16123
  // 40 real Claude Code turns, moving this from 10 to 1 took searches from 15% of turns to 32.5%
@@ -16052,11 +16137,15 @@ function resolveConfig(raw = {}) {
16052
16137
  // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
16053
16138
  // nested object cannot reach the API as a tag and fail the whole retain.
16054
16139
  retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
16140
+ // Undefined, not "", when unset or blank: the retain call distinguishes "not configured" (use
16141
+ // the built-in default) from a configured value, and an empty context would strip the default.
16142
+ retainContext: typeof raw.retainContext === "string" && raw.retainContext.trim() !== "" ? raw.retainContext : void 0,
16055
16143
  retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
16056
16144
  Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
16057
16145
  ) : {},
16058
16146
  observationScopes: resolveObservationScopes(raw.observationScopes),
16059
16147
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
16148
+ paths: raw.paths && typeof raw.paths === "object" ? raw.paths : {},
16060
16149
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info",
16061
16150
  autoUpdate: raw.autoUpdate ?? true
16062
16151
  };
@@ -16073,7 +16162,12 @@ function readRaw(path) {
16073
16162
  }
16074
16163
  function mergeRaw(a, b) {
16075
16164
  const { harnesses: _drop, ...flat } = b;
16076
- return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
16165
+ return {
16166
+ ...a,
16167
+ ...flat,
16168
+ banks: { ...a.banks ?? {}, ...b.banks ?? {} },
16169
+ paths: { ...a.paths ?? {}, ...b.paths ?? {} }
16170
+ };
16077
16171
  }
16078
16172
  function applyLayer(raw, layer, harness) {
16079
16173
  let out = mergeRaw(raw, layer);
@@ -16104,9 +16198,11 @@ var ENV_KEYS = {
16104
16198
  maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
16105
16199
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
16106
16200
  reflectToolTimeoutMs: "HINDSIGHT_REFLECT_TOOL_TIMEOUT_MS",
16201
+ injectTimeoutMs: "HINDSIGHT_INJECT_TIMEOUT_MS",
16107
16202
  reflectBudget: "HINDSIGHT_REFLECT_BUDGET",
16108
16203
  autoInject: "HINDSIGHT_AUTO_INJECT",
16109
16204
  pageSearchLimit: "HINDSIGHT_PAGE_SEARCH_LIMIT",
16205
+ toolGuideExtra: "HINDSIGHT_TOOL_GUIDE_EXTRA",
16110
16206
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
16111
16207
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
16112
16208
  pageTriggerType: "HINDSIGHT_PAGE_TRIGGER_TYPE",
@@ -16148,6 +16244,7 @@ var ENV_NUMBERS = /* @__PURE__ */ new Set([
16148
16244
  "maxParallelRetains",
16149
16245
  "reflectTimeoutMs",
16150
16246
  "reflectToolTimeoutMs",
16247
+ "injectTimeoutMs",
16151
16248
  "pageSearchLimit",
16152
16249
  "pageRefreshEveryTurns",
16153
16250
  "seedLimit",
@@ -16196,15 +16293,25 @@ var BANK_OVERRIDE_EXCLUDED = [
16196
16293
  function applyBankConfig(cfg, resolvedId, directory) {
16197
16294
  if (directory !== void 0 && !isOptedIn(cfg, directory))
16198
16295
  return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
16296
+ const byPath = directory === void 0 ? void 0 : pathSection(cfg, cfg.paths, directory);
16297
+ if (byPath) {
16298
+ const { bank: _rename, ...rest } = overrideFields(byPath);
16299
+ cfg = { ...cfg, ...resolvePartial(cfg, rest) };
16300
+ }
16199
16301
  const section = cfg.banks[resolvedId];
16200
16302
  if (!section) return { cfg, bankId: resolvedId };
16201
- const safe = { ...section };
16202
- for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
16203
- delete safe.banks;
16303
+ const safe = overrideFields(section);
16204
16304
  const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
16205
16305
  delete safe.bank;
16206
16306
  return { cfg: { ...cfg, ...resolvePartial(cfg, safe) }, bankId };
16207
16307
  }
16308
+ function overrideFields(section) {
16309
+ const safe = { ...section };
16310
+ for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
16311
+ delete safe.banks;
16312
+ delete safe.paths;
16313
+ return safe;
16314
+ }
16208
16315
  function resolvePartial(cfg, patch) {
16209
16316
  const full = resolveConfig(patch);
16210
16317
  const out = {};
@@ -16213,6 +16320,16 @@ function resolvePartial(cfg, patch) {
16213
16320
  out[key] = full[key];
16214
16321
  }
16215
16322
  if ("autoReflect" in patch && !("autoInject" in patch)) out.autoInject = full.autoInject;
16323
+ if ("serverMode" in patch || "apiUrl" in patch || "apiPort" in patch) {
16324
+ const conn = resolveConfig({
16325
+ serverMode: patch.serverMode ?? cfg.serverMode,
16326
+ apiPort: patch.apiPort ?? cfg.apiPort,
16327
+ apiUrl: patch.apiUrl ?? (cfg.serverMode === "daemon" ? void 0 : cfg.apiUrl)
16328
+ });
16329
+ out.serverMode = conn.serverMode;
16330
+ out.apiUrl = conn.apiUrl;
16331
+ out.apiPort = conn.apiPort;
16332
+ }
16216
16333
  return out;
16217
16334
  }
16218
16335
 
@@ -16241,7 +16358,12 @@ function resolveHostMemory(harness, directory) {
16241
16358
  // rotate the key mid-session and the snapshot 401s every call until restart (#3600). Read
16242
16359
  // through the same pipeline the constructor used, so a per-bank `banks.<id>.apiToken` is
16243
16360
  // honoured on re-resolution exactly as it was on the first one.
16244
- tokenProvider: () => resolveHostConfig(harness, directory).cfg.apiToken
16361
+ // The URL stays the one this client was built with, so a token re-read after the config
16362
+ // moved this directory to ANOTHER server is that server's credential: never send it here.
16363
+ tokenProvider: () => {
16364
+ const live = resolveHostConfig(harness, directory).cfg;
16365
+ return live.apiUrl === cfg.apiUrl ? live.apiToken : cfg.apiToken;
16366
+ }
16245
16367
  })
16246
16368
  };
16247
16369
  }
@@ -16567,12 +16689,46 @@ function startDaemonDetached(cfg, harness, spawnFn = realSpawn3) {
16567
16689
  } catch {
16568
16690
  }
16569
16691
  }
16692
+ var coldStarts = /* @__PURE__ */ new Map();
16693
+ async function waitBounded(p, ms) {
16694
+ let timer;
16695
+ try {
16696
+ await Promise.race([
16697
+ p,
16698
+ new Promise((resolve3) => {
16699
+ timer = setTimeout(resolve3, Math.max(ms, 0));
16700
+ })
16701
+ ]);
16702
+ } finally {
16703
+ clearTimeout(timer);
16704
+ }
16705
+ }
16570
16706
  async function ensureDaemon(cfg, harness, opts = {}) {
16571
16707
  if (cfg.serverMode !== "daemon") return;
16572
16708
  if (await isServerHealthy(cfg.apiUrl)) return;
16573
16709
  if (!preflightDaemon(cfg, harness)) return;
16574
- startDaemonDetached(cfg, harness, opts.spawnFn);
16575
- await waitForHealth(cfg.apiUrl, opts.waitMs ?? 0);
16710
+ const waitMs = opts.waitMs ?? 0;
16711
+ const running = coldStarts.get(cfg.apiUrl);
16712
+ if (running) {
16713
+ const startedAt = Date.now();
16714
+ await waitBounded(
16715
+ running.catch(() => void 0),
16716
+ waitMs
16717
+ );
16718
+ const remaining = waitMs - (Date.now() - startedAt);
16719
+ if (remaining > 0) await waitForHealth(cfg.apiUrl, remaining);
16720
+ return;
16721
+ }
16722
+ const attempt = (async () => {
16723
+ startDaemonDetached(cfg, harness, opts.spawnFn);
16724
+ await waitForHealth(cfg.apiUrl, waitMs);
16725
+ })();
16726
+ coldStarts.set(cfg.apiUrl, attempt);
16727
+ try {
16728
+ await attempt;
16729
+ } finally {
16730
+ if (coldStarts.get(cfg.apiUrl) === attempt) coldStarts.delete(cfg.apiUrl);
16731
+ }
16576
16732
  }
16577
16733
  async function waitForHealth(baseUrl, budgetMs, pollMs = 1e3) {
16578
16734
  const deadline = Date.now() + budgetMs;
@@ -16624,13 +16780,13 @@ function indexLine(pages) {
16624
16780
  const count = pages.length === 1 ? "1 knowledge page covers" : `${pages.length} knowledge pages cover`;
16625
16781
  return `${count} this repository \u2014 architecture, conventions, past decisions and in-flight initiatives. They are deliberately NOT listed here: call hindsight_search_knowledge_pages(query) to find the ones that bear on the current turn, then hindsight_read_knowledge_page(<id>) on anything the results show is worth reading in full.`;
16626
16782
  }
16627
- var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, and the way IN to everything below. The code shows what is true today, never what was decided or why, so work built from code alone quietly re-litigates settled questions. Search BEFORE you act whenever the turn is one of these \u2014 they are the ones that go wrong silently:
16628
- \u2022 the user reports a bug or a wrong response (the intended behaviour, and the status code or value it should return, is usually already decided);
16783
+ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, and the way IN to everything below. The code shows what is true today but not what was decided or why; memory shows what was decided or said back then but not whether it still holds. Work built from either alone goes wrong: from code alone it quietly re-litigates settled questions, from memory alone it acts on stale claims. Search BEFORE you act whenever the turn is one of these \u2014 they are the ones that go wrong silently:
16784
+ \u2022 the user reports a bug or a wrong response (the intended behaviour, and the status code or value it should return, may already have been decided);
16629
16785
  \u2022 you are about to write or change a test (what this project expects a change to ship with, and how it asserts, is a convention, not a preference);
16630
16786
  \u2022 you are implementing something new, or two parts have to fit together;
16631
16787
  \u2022 the user asks why something is the way it is, or what is left to do;
16632
16788
  \u2022 you are about to commit, and need to know what the change was supposed to honour.
16633
- It ranks the pages by relevance and returns the matching passage, which a page title cannot tell you.
16789
+ It ranks the pages by relevance and returns the matching passage, which a page title cannot tell you. What it returns is a past record, not a live reading: a claim that something was fixed, passes, or works is what someone said then \u2014 check it against the code before you rely on it, and say so when the two disagree.
16634
16790
  CREDITING IS NOT OPTIONAL AND NOT A JUDGEMENT CALL. If you called this tool and anything it returned reached your reply \u2014 quoted, paraphrased, or merely confirming what you were about to say \u2014 open that part with a markdown blockquote, exactly: "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. A search that turned up nothing useful needs no mention at all \u2014 just carry on.
16635
16791
  - hindsight_list_knowledge_pages / hindsight_read_knowledge_page \u2014 BEFORE substantial work, list the pages and read the relevant ones to ground yourself in this repo's architecture, conventions, and past decisions instead of re-deriving them from the code; follow any [[page:<id>]] links you see.
16636
16792
  - hindsight_reflect(query) \u2014 when pages are too shallow and you need the WHY: deep reasoning over the repo's full memory for the past decision and exact values that explain a behavior or bug (slower \u2014 use deliberately, and credit results with a blockquote header "> \u{1F9E0} **From Hindsight memory** \u2014 <summary>").
@@ -16638,7 +16794,9 @@ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, a
16638
16794
  - hindsight_ingest_document(title, content) \u2014 save an external document or durable notes/findings you want remembered (not the current conversation \u2014 that is captured automatically at session end).`;
16639
16795
  var PAGES_FIRST_ON_GOALS = "- The user just set a NEW task or goal \u2192 search the knowledge pages FIRST with hindsight_search_knowledge_pages. No synthesis is injected automatically in this configuration; call hindsight_reflect only when those pages are too shallow and deeper reasoning is needed.\n";
16640
16796
  function toolGuide(opts) {
16641
- return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE;
16797
+ const extra = opts?.extra?.trim();
16798
+ return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE + (extra ? `
16799
+ ${extra}` : "");
16642
16800
  }
16643
16801
  function buildKnowledgePreamble(pages, opts) {
16644
16802
  const body = pages.length ? indexLine(pages) : EMPTY_STATE;
@@ -16670,6 +16828,7 @@ import { execFileSync as execFileSync3 } from "child_process";
16670
16828
  // src/core/git.ts
16671
16829
  import { execFileSync as execFileSync2 } from "child_process";
16672
16830
  import { resolve as resolve2 } from "path";
16831
+ var GITLOG_HEAD = "gitlog-head:";
16673
16832
  function git(repo, ...args) {
16674
16833
  return execFileSync2("git", ["-C", repo, ...args], {
16675
16834
  encoding: "utf8",
@@ -16691,6 +16850,7 @@ function gitHeadSha(dir) {
16691
16850
  }
16692
16851
  }
16693
16852
  function commitsSince(dir, sinceSha) {
16853
+ if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(sinceSha)) return null;
16694
16854
  try {
16695
16855
  const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
16696
16856
  return Number.isFinite(n) ? n : null;
@@ -16705,6 +16865,15 @@ function hasGitHistory(dir) {
16705
16865
  return false;
16706
16866
  }
16707
16867
  }
16868
+ async function gitLogIsCurrent(client, repo, head) {
16869
+ const canonical2 = `gitlog:${repoNameOf(repo)}`;
16870
+ if ((await client.listDocumentIds(`${GITLOG_HEAD}${head}`, "all_strict")).has(canonical2))
16871
+ return true;
16872
+ const tags = await client.documentTags?.(canonical2) ?? [];
16873
+ return tags.some(
16874
+ (tag) => tag.startsWith(GITLOG_HEAD) && commitsSince(repo, tag.slice(GITLOG_HEAD.length)) === 0
16875
+ );
16876
+ }
16708
16877
 
16709
16878
  // src/core/survey.ts
16710
16879
  import { spawn as realSpawn5 } from "child_process";
@@ -17056,19 +17225,7 @@ var NON_DESTRUCTIVE_WRITE_ANNOTATIONS = {
17056
17225
  idempotentHint: false,
17057
17226
  openWorldHint: false
17058
17227
  };
17059
- var CREDIT_REMINDER = 'Crediting is mandatory, not a judgement call: if anything these results contribute reaches your reply \u2014 quoted, paraphrased, or merely confirming what you were going to say \u2014 open that part with "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. If none of them bear on the turn, ignore them silently \u2014 an unhelpful search needs no mention.';
17060
- function shapePage(page) {
17061
- const p = page ?? {};
17062
- const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
17063
- return {
17064
- id: p.id,
17065
- name: p.name,
17066
- ...p.description ? { description: p.description } : {},
17067
- ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
17068
- ...p.timestamp ? { last_updated_at: p.timestamp } : {},
17069
- body
17070
- };
17071
- }
17228
+ var CREDIT_REMINDER = 'Crediting is mandatory, not a judgement call: if anything these results contribute reaches your reply \u2014 quoted, paraphrased, or merely confirming what you were going to say \u2014 open that part with "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. If none of them bear on the turn, ignore them silently \u2014 an unhelpful search needs no mention. These are past records: check a claim that something was fixed or works against the code before relying on it.';
17072
17229
  function ok(value) {
17073
17230
  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
17074
17231
  }
@@ -17086,6 +17243,8 @@ function guarded(fn) {
17086
17243
  };
17087
17244
  }
17088
17245
  function buildKnowledgeTools(client, bankId, opts = {}) {
17246
+ const extra = opts.toolGuideExtra?.trim();
17247
+ const crediting = extra ? `${CREDIT_REMINDER} ${extra}` : CREDIT_REMINDER;
17089
17248
  return [
17090
17249
  {
17091
17250
  name: "hindsight_sync_status",
@@ -17145,7 +17304,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17145
17304
  },
17146
17305
  {
17147
17306
  name: "hindsight_search_knowledge_pages",
17148
- description: "Search this repository's Hindsight knowledge pages for content relevant to a query \u2014 hybrid full-text + semantic search, server-side. Call this when the user's question may be answered by the project's accumulated knowledge (architecture, conventions, decisions, initiatives) rather than by reading code. Returns ranked pages with a relevance snippet; read a full page with hindsight_read_knowledge_page. " + CREDIT_REMINDER,
17307
+ description: "Search this repository's Hindsight knowledge pages for content relevant to a query \u2014 hybrid full-text + semantic search, server-side. Call this when the user's question may be answered by the project's accumulated knowledge (architecture, conventions, decisions, initiatives) rather than by reading code. Returns ranked pages with a relevance snippet; read a full page with hindsight_read_knowledge_page. " + crediting,
17149
17308
  inputSchema: { query: external_exports.string().describe("what to look for") },
17150
17309
  annotations: READ_ONLY_ANNOTATIONS,
17151
17310
  handler: async (args) => {
@@ -17155,9 +17314,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17155
17314
  pages: hits.map((h) => ({
17156
17315
  page: h.name,
17157
17316
  page_id: h.id,
17317
+ // The question the page answers — the same `description` the list and read tools
17318
+ // carry, so a hit says what the page is FOR, not just how it opens.
17319
+ ...h.source_query ? { description: h.source_query } : {},
17158
17320
  snippet: h.snippet
17159
17321
  })),
17160
- crediting: CREDIT_REMINDER
17322
+ crediting
17161
17323
  });
17162
17324
  } catch (e) {
17163
17325
  return err(e);
@@ -17176,7 +17338,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17176
17338
  description: "Read the full content of one knowledge page by its id (from hindsight_list_knowledge_pages). Call this whenever a listed page is relevant to what you're about to do \u2014 e.g. read Conventions before writing new code, Component map before changing a subsystem, or an initiative's page before continuing that feature. A page may contain [[page:<id>]] links to related pages; follow one by calling this tool again with that id. Prefer reading a page over re-deriving the same understanding from source.",
17177
17339
  inputSchema: { page_id: external_exports.string() },
17178
17340
  annotations: READ_ONLY_ANNOTATIONS,
17179
- handler: guarded(async ({ page_id }) => shapePage(await client.getPage(page_id)))
17341
+ handler: guarded(async ({ page_id }) => client.getPage(page_id))
17180
17342
  },
17181
17343
  {
17182
17344
  name: "hindsight_reflect",
@@ -17246,6 +17408,11 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17246
17408
  import { createHash as createHash4 } from "crypto";
17247
17409
  var PENDING_MAX_AGE_MS = 12 * 60 * 60 * 1e3;
17248
17410
  var PENDING_MAX_BYTES = 256 * 1024;
17411
+ var MAX_CURSOR_PATHS = 16;
17412
+ function advancePaths(seen, path) {
17413
+ if (!path) return seen;
17414
+ return [...(seen ?? []).filter((p) => p !== path), path].slice(-MAX_CURSOR_PATHS);
17415
+ }
17249
17416
  function pendingReplayable(cursor, now) {
17250
17417
  const pending = cursor.pending ?? [];
17251
17418
  if (!pending.length) return true;
@@ -17262,8 +17429,10 @@ function planRetain(turns, cursor, opts) {
17262
17429
  if (!opts.appendSupported || !cursor || cursor.dirty) return { mode: "replace" };
17263
17430
  if (!pendingReplayable(cursor, opts.now ?? Date.now())) return { mode: "replace" };
17264
17431
  if (cursor.bank !== opts.bank) return { mode: "replace" };
17265
- if (cursor.turns > turns.length) return { mode: "replace" };
17266
- if (fingerprintTurns(turns, cursor.turns) !== cursor.fingerprint) return { mode: "replace" };
17432
+ const seen = cursor.paths ?? [];
17433
+ const newFile = Boolean(opts.path && seen.length && !seen.includes(opts.path));
17434
+ const continues = cursor.turns <= turns.length && fingerprintTurns(turns, cursor.turns) === cursor.fingerprint;
17435
+ if (!continues) return newFile ? { mode: "append", fromTurn: 0 } : { mode: "replace" };
17267
17436
  if (cursor.turns === turns.length) return { mode: "skip" };
17268
17437
  return { mode: "append", fromTurn: cursor.turns };
17269
17438
  }
@@ -17305,7 +17474,7 @@ function renderSessionJsonl(refId, turns, baseTs) {
17305
17474
  }
17306
17475
  async function supportsAppend(client) {
17307
17476
  try {
17308
- return await client.supportsIdempotentRetain();
17477
+ return await client.supportsAppendRetain();
17309
17478
  } catch {
17310
17479
  return false;
17311
17480
  }
@@ -17339,6 +17508,7 @@ function serialize(cursors, sessionId, write2) {
17339
17508
  });
17340
17509
  return next;
17341
17510
  }
17511
+ var DEFAULT_RETAIN_CONTEXT = `conversation between the user and you (the coding agent): user turns are the user's words and decisions, assistant turns are yours. When an assistant turn says something is fixed, passes or works, record it as the agent's claim ("the agent reported X fixed"), not as an established fact.`;
17342
17512
  async function retainLiveSession(client, sessionId, turns, startTs, harness, opts = {}) {
17343
17513
  const cursors = opts.cursors;
17344
17514
  if (!cursors)
@@ -17350,20 +17520,36 @@ async function retainLiveSession(client, sessionId, turns, startTs, harness, opt
17350
17520
  harness,
17351
17521
  opts.stamp,
17352
17522
  void 0,
17353
- opts.retryUntil
17523
+ opts.retryUntil,
17524
+ opts.transcriptPath
17354
17525
  );
17355
17526
  return serialize(
17356
17527
  cursors,
17357
17528
  sessionId,
17358
- () => writeSession(client, sessionId, turns, startTs, harness, opts.stamp, cursors, opts.retryUntil)
17529
+ () => writeSession(
17530
+ client,
17531
+ sessionId,
17532
+ turns,
17533
+ startTs,
17534
+ harness,
17535
+ opts.stamp,
17536
+ cursors,
17537
+ opts.retryUntil,
17538
+ opts.transcriptPath
17539
+ )
17359
17540
  );
17360
17541
  }
17361
- async function writeSession(client, sessionId, turns, startTs, harness, stamp, cursors, retryUntil = Date.now() + DEFAULT_RETRY_WINDOW_MS) {
17542
+ async function writeSession(client, sessionId, turns, startTs, harness, stamp, cursors, retryUntil = Date.now() + DEFAULT_RETRY_WINDOW_MS, transcriptPath) {
17362
17543
  if (!turns.length) return;
17363
17544
  const refId = `conversation:${sessionId}`;
17364
17545
  const cursor = cursors?.read(sessionId);
17365
17546
  const appendSupported = Boolean(cursors) && (cursor?.appendSupported === true || await supportsAppend(client));
17366
- const plan = planRetain(turns, cursor, { appendSupported, bank: client.bank });
17547
+ const plan = planRetain(turns, cursor, {
17548
+ appendSupported,
17549
+ bank: client.bank,
17550
+ path: transcriptPath
17551
+ });
17552
+ const paths = plan.mode === "replace" ? transcriptPath ? [transcriptPath] : void 0 : advancePaths(cursor?.paths, transcriptPath);
17367
17553
  const outbox = plan.mode === "replace" ? [] : cursor?.pending ?? [];
17368
17554
  if (plan.mode === "skip" && !outbox.length) return;
17369
17555
  const opId = (mode, content) => uuidV5(`${client.bank}
@@ -17372,7 +17558,10 @@ ${mode}
17372
17558
  ${content}`);
17373
17559
  const submit = (content, operationId, append) => client.retain(
17374
17560
  content,
17375
- "coding agent session",
17561
+ // Configured context wins. Extraction reads this to decide whose claim a sentence is, so the
17562
+ // default names both speakers: the previous "coding agent session" said nothing about
17563
+ // authorship and let an assistant's proposal be recorded as the user's decision.
17564
+ stamp?.context ?? DEFAULT_RETAIN_CONTEXT,
17376
17565
  refId,
17377
17566
  // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
17378
17567
  // the documents list filters and draws its agent logo from, so a template cannot displace them.
@@ -17402,6 +17591,7 @@ ${content}`);
17402
17591
  turns: turns.length,
17403
17592
  fingerprint: fingerprintTurns(turns, turns.length),
17404
17593
  bank: client.bank,
17594
+ ...paths ? { paths } : {},
17405
17595
  ...appendSupported ? { appendSupported: true } : {}
17406
17596
  };
17407
17597
  const stillOurs = () => {
@@ -17518,7 +17708,8 @@ function resolversFor(ctx) {
17518
17708
  function buildRetainStamp(cfg, ctx) {
17519
17709
  const hasTags = Boolean(cfg.retainTags?.length);
17520
17710
  const hasMetadata = Boolean(cfg.retainMetadata && Object.keys(cfg.retainMetadata).length);
17521
- if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
17711
+ const hasContext = Boolean(cfg.retainContext?.trim());
17712
+ if (!hasTags && !hasMetadata && !hasContext) return { tags: [], metadata: {} };
17522
17713
  const base = resolversFor(ctx);
17523
17714
  const cache = /* @__PURE__ */ new Map();
17524
17715
  const resolvers = Object.fromEntries(
@@ -17542,19 +17733,22 @@ function buildRetainStamp(cfg, ctx) {
17542
17733
  for (const [key, value] of Object.entries(cfg.retainMetadata ?? {})) {
17543
17734
  metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
17544
17735
  }
17545
- return { tags, metadata };
17736
+ const context = hasContext ? applyTemplate(cfg.retainContext, resolvers, "retainContext").trim() || void 0 : void 0;
17737
+ return { tags, metadata, context };
17546
17738
  }
17547
17739
 
17548
17740
  // src/core/session-start.ts
17549
17741
  import { readFileSync as readFileSync8 } from "fs";
17550
17742
 
17551
17743
  // src/core/skill-sync.ts
17552
- import { cpSync, existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
17744
+ import { cpSync, existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
17553
17745
  import { homedir as homedir7 } from "os";
17554
- import { dirname as dirname8, join as join14 } from "path";
17746
+ import { dirname as dirname8, join as join15 } from "path";
17555
17747
  import { fileURLToPath as fileURLToPath5 } from "url";
17556
17748
 
17557
17749
  // src/core/skill-dirs.ts
17750
+ import { existsSync as existsSync5 } from "fs";
17751
+ import { join as join14 } from "path";
17558
17752
  var SKILL_DIRS = {
17559
17753
  "claude-code": [".claude", "skills"],
17560
17754
  // Codex and dsh share the agentskills-standard root; uninstalling either removes the one copy.
@@ -17567,6 +17761,8 @@ var SKILL_DIRS = {
17567
17761
  "cline-cli": [".cline", "data", "settings", "skills"],
17568
17762
  "qwen-code": [".qwen", "skills"],
17569
17763
  // Qwen's user-level skills root (Storage.getUserSkillsDirs)
17764
+ // Kimi Code's user-level skills root, alongside its config.toml and mcp.json.
17765
+ "kimi-code": [".kimi-code", "skills"],
17570
17766
  "factory-droid": [".factory", "skills"],
17571
17767
  // Droid's user-level skills root
17572
17768
  // ZCode scans TWO user roots by default (its resolveDefaultSkillRoots): `~/.zcode/skills` and the
@@ -17574,29 +17770,46 @@ var SKILL_DIRS = {
17574
17770
  // skill removal is by fixed directory name, so installing into the shared root would make
17575
17771
  // `uninstall zcode` take Codex's and dsh's copy with it.
17576
17772
  zcode: [".zcode", "skills"],
17773
+ // TraeCode's user-level skills root, resolved per edition by traecodeDotDir below — like ZCode's
17774
+ // its own, never the shared agentskills root other hosts install into.
17775
+ traecode: [".trae-cn", "skills"],
17577
17776
  // The pi family reads the shared ~/.agents/skills too, but writes its OWN root: skill removal is
17578
17777
  // by fixed directory name, so installing to the shared one would make `uninstall pi` take Codex's
17579
17778
  // and dsh's copy with it.
17580
17779
  pi: [".pi", "agent", "skills"],
17581
17780
  "prime-agent": [".prime", "agent", "skills"]
17582
17781
  };
17782
+ var TRAE_DOT_DIRS = [".trae-cn", ".trae"];
17783
+ var traecodeDotDirName = (home, exists = existsSync5) => {
17784
+ for (const dir of TRAE_DOT_DIRS) {
17785
+ if (exists(join14(home, dir))) return dir;
17786
+ }
17787
+ return ".trae-cn";
17788
+ };
17789
+ var resolveSkillDirs = (harness, home) => {
17790
+ const parts = SKILL_DIRS[harness];
17791
+ if (harness === "traecode" && parts) {
17792
+ return [traecodeDotDirName(home), ...parts.slice(1)];
17793
+ }
17794
+ return parts;
17795
+ };
17583
17796
 
17584
17797
  // src/core/skill-sync.ts
17585
17798
  function packagedSkillDir() {
17586
17799
  const here = dirname8(fileURLToPath5(import.meta.url));
17587
- const dist = join14(here, "..", "skill");
17588
- return existsSync5(join14(dist, "SKILL.md")) ? dist : join14(here, "..", "..", "skill");
17800
+ const dist = join15(here, "..", "skill");
17801
+ return existsSync6(join15(dist, "SKILL.md")) ? dist : join15(here, "..", "..", "skill");
17589
17802
  }
17590
17803
  function syncCompanionSkill(harness, opts = {}) {
17591
17804
  try {
17592
- const parts = SKILL_DIRS[harness];
17805
+ const parts = resolveSkillDirs(harness, opts.home ?? homedir7());
17593
17806
  if (!parts) return;
17594
17807
  const src = opts.srcDir ?? packagedSkillDir();
17595
- const srcMd = join14(src, "SKILL.md");
17596
- if (!existsSync5(srcMd)) return;
17597
- const dst = join14(opts.home ?? homedir7(), ...parts, "hindsight-coding-agent");
17598
- const dstMd = join14(dst, "SKILL.md");
17599
- const installed = existsSync5(dstMd);
17808
+ const srcMd = join15(src, "SKILL.md");
17809
+ if (!existsSync6(srcMd)) return;
17810
+ const dst = join15(opts.home ?? homedir7(), ...parts, "hindsight-coding-agent");
17811
+ const dstMd = join15(dst, "SKILL.md");
17812
+ const installed = existsSync6(dstMd);
17600
17813
  if (!installed && !opts.install) return;
17601
17814
  if (!installed || readFileSync5(srcMd, "utf8") !== readFileSync5(dstMd, "utf8")) {
17602
17815
  cpSync(src, dst, { recursive: true });
@@ -17620,15 +17833,15 @@ function brandWord() {
17620
17833
  }
17621
17834
 
17622
17835
  // src/core/legacy.ts
17623
- import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
17836
+ import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
17624
17837
  import { homedir as homedir8 } from "os";
17625
- import { join as join15, relative, isAbsolute as isAbsolute2 } from "path";
17838
+ import { join as join16, relative, isAbsolute as isAbsolute2 } from "path";
17626
17839
  var LEGACY_CLAUDE_PLUGIN = "hindsight-memory";
17627
- function detectLegacyClaudePlugin(cwd, claudeDir = join15(homedir8(), ".claude")) {
17628
- const registry2 = readJson(join15(claudeDir, "plugins", "installed_plugins.json"));
17840
+ function detectLegacyClaudePlugin(cwd, claudeDir = join16(homedir8(), ".claude")) {
17841
+ const registry2 = readJson(join16(claudeDir, "plugins", "installed_plugins.json"));
17629
17842
  const plugins = registry2?.plugins;
17630
17843
  if (!plugins || typeof plugins !== "object") return void 0;
17631
- const enabled = readJson(join15(claudeDir, "settings.json"))?.enabledPlugins;
17844
+ const enabled = readJson(join16(claudeDir, "settings.json"))?.enabledPlugins;
17632
17845
  for (const [key, raw] of Object.entries(plugins)) {
17633
17846
  if (key.split("@")[0] !== LEGACY_CLAUDE_PLUGIN) continue;
17634
17847
  if (enabled && enabled[key] === false) continue;
@@ -17659,9 +17872,9 @@ function legacyClaudePluginWarning(key) {
17659
17872
  // src/core/session-cache.ts
17660
17873
  import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync3, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
17661
17874
  import { tmpdir as tmpdir3 } from "os";
17662
- import { dirname as dirname9, join as join16 } from "path";
17875
+ import { dirname as dirname9, join as join17 } from "path";
17663
17876
  function sessionCacheFile(harness, sessionId) {
17664
- return join16(tmpdir3(), `hindsight-${harness}`, `${sessionId}.json`);
17877
+ return join17(tmpdir3(), `hindsight-${harness}`, `${sessionId}.json`);
17665
17878
  }
17666
17879
  function readSessionCache(cacheFile) {
17667
17880
  try {
@@ -17703,7 +17916,7 @@ async function gitSyncNote(args) {
17703
17916
  if (mode === "none" || cold) return void 0;
17704
17917
  const head = gitHeadSha(cwd);
17705
17918
  if (!head) return void 0;
17706
- const gitlogCurrent = await client.listDocumentIds(`gitlog-head:${head}`, "all_strict").then((s) => s.has(`gitlog:${repoNameOf(cwd)}`)).catch(() => void 0);
17919
+ const gitlogCurrent = await gitLogIsCurrent(client, cwd, head).catch(() => void 0);
17707
17920
  if (gitlogCurrent === void 0) return void 0;
17708
17921
  if (mode === "message") return gitlogCurrent ? "git in sync" : "catching up on new commits";
17709
17922
  const deepened = [...gitIds].filter((id) => id.startsWith("git:")).length;
@@ -17829,7 +18042,8 @@ async function buildSessionStartContext(args) {
17829
18042
  }
17830
18043
  }
17831
18044
  const additionalContext = buildKnowledgePreamble(pages, {
17832
- reflectOnNewGoals: cfg.autoInject !== "reflect"
18045
+ reflectOnNewGoals: cfg.autoInject !== "reflect",
18046
+ extra: cfg.toolGuideExtra
17833
18047
  });
17834
18048
  const deferInitialReflect = cold === true || pageListKnown && pages.length === 0;
17835
18049
  let gitNote;
@@ -17855,7 +18069,7 @@ ${legacyClaudePluginWarning(legacyPlugin)}`;
17855
18069
  }
17856
18070
 
17857
18071
  // src/core/hook.ts
17858
- import { existsSync as existsSync7, readFileSync as readFileSync10 } from "fs";
18072
+ import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
17859
18073
 
17860
18074
  // src/core/inject.ts
17861
18075
  function buildReflectQuery(prompt) {
@@ -17904,7 +18118,7 @@ If you VERIFY this memory is wrong or outdated (the code or facts contradict it)
17904
18118
  // src/core/turn-journal.ts
17905
18119
  import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync5, readFileSync as readFileSync9, statSync as statSync3 } from "fs";
17906
18120
  import { tmpdir as tmpdir4 } from "os";
17907
- import { dirname as dirname10, join as join17 } from "path";
18121
+ import { dirname as dirname10, join as join18 } from "path";
17908
18122
 
17909
18123
  // src/core/transcript-util.ts
17910
18124
  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;
@@ -17945,7 +18159,6 @@ function actionLine(tool, input) {
17945
18159
  var JOURNAL_MAX_BYTES = 8 * 1024 * 1024;
17946
18160
 
17947
18161
  // src/core/hook.ts
17948
- var HOOK_FALLBACK_BUDGET_MS = 7e3;
17949
18162
  var HOOK_INJECT_ATTEMPTS = 2;
17950
18163
  function resolveInjection(got, attempts) {
17951
18164
  if (got != null) return got;
@@ -17973,8 +18186,8 @@ async function injectRecall(harness, prompt, client, timeoutMs, event, lead) {
17973
18186
  return void 0;
17974
18187
  }
17975
18188
  }
17976
- async function reflectFallback(harness, prompt, client) {
17977
- const deadline = Date.now() + HOOK_FALLBACK_BUDGET_MS;
18189
+ async function reflectFallback(harness, prompt, client, timeoutMs) {
18190
+ const deadline = Date.now() + timeoutMs;
17978
18191
  const remaining = () => Math.max(deadline - Date.now(), 1);
17979
18192
  return await injectPages(harness, prompt, client, remaining(), "reflect_fallback_pages") ?? // Event name predates the `injectRecall` rename and is kept: it is a logged contract that
17980
18193
  // other tools read, so renaming it would silently break them.
@@ -17999,7 +18212,7 @@ async function buildHookOutput(args) {
17999
18212
  harness,
18000
18213
  prompt,
18001
18214
  client,
18002
- HOOK_FALLBACK_BUDGET_MS,
18215
+ cfg.injectTimeoutMs,
18003
18216
  "inject_pages",
18004
18217
  PAGE_INJECT_LEAD
18005
18218
  );
@@ -18012,7 +18225,7 @@ async function buildHookOutput(args) {
18012
18225
  harness,
18013
18226
  prompt,
18014
18227
  client,
18015
- HOOK_FALLBACK_BUDGET_MS,
18228
+ cfg.injectTimeoutMs,
18016
18229
  "inject_recall",
18017
18230
  RECALL_INJECT_LEAD
18018
18231
  );
@@ -18054,7 +18267,7 @@ async function buildHookOutput(args) {
18054
18267
  query: prompt.slice(0, 80)
18055
18268
  });
18056
18269
  if (e instanceof ReflectError && e.fallbackEligible) {
18057
- fallback = await reflectFallback(harness, prompt, client);
18270
+ fallback = await reflectFallback(harness, prompt, client, cfg.injectTimeoutMs);
18058
18271
  if (fallback) reflectAnswer = fallback;
18059
18272
  }
18060
18273
  }
@@ -18087,7 +18300,12 @@ async function buildHookOutput(args) {
18087
18300
  const blocks = [];
18088
18301
  if (reflectAnswer && reflectRanThisTurn) blocks.push(buildSystemInjection(reflectAnswer));
18089
18302
  if (cadence > 0 && turns % cadence === 0) {
18090
- blocks.push(buildRosterRefresh(pages, { reflectOnNewGoals: cfg.autoInject !== "reflect" }));
18303
+ blocks.push(
18304
+ buildRosterRefresh(pages, {
18305
+ reflectOnNewGoals: cfg.autoInject !== "reflect",
18306
+ extra: cfg.toolGuideExtra
18307
+ })
18308
+ );
18091
18309
  }
18092
18310
  const kept = blocks.filter(Boolean);
18093
18311
  let notice;
@@ -18156,6 +18374,7 @@ var RuntimeCore = class {
18156
18374
  pageTrigger: buildPageTrigger(this.cfg),
18157
18375
  reflectTimeoutMs: this.cfg.reflectToolTimeoutMs,
18158
18376
  reflectBudget: this.cfg.reflectBudget,
18377
+ toolGuideExtra: this.cfg.toolGuideExtra,
18159
18378
  stampFor: () => buildRetainStamp(this.cfg, {
18160
18379
  directory: this.projectDir,
18161
18380
  harness: this.harness,
@@ -18223,7 +18442,8 @@ var RuntimeCore = class {
18223
18442
  if (turns === 1) {
18224
18443
  blocks.push(
18225
18444
  buildKnowledgePreamble(output.pages, {
18226
- reflectOnNewGoals: this.cfg.autoInject !== "reflect"
18445
+ reflectOnNewGoals: this.cfg.autoInject !== "reflect",
18446
+ extra: this.cfg.toolGuideExtra
18227
18447
  })
18228
18448
  );
18229
18449
  }
@@ -18420,6 +18640,10 @@ function createPiHooks(core, harness, sessionStart) {
18420
18640
  return void 0;
18421
18641
  }
18422
18642
  diag(harness, "inject_ok", { session: sessionId, chars: injection.length });
18643
+ if (event.systemPromptOptions?.sections) {
18644
+ event.systemPromptOptions.sections.hindsight = injection;
18645
+ return void 0;
18646
+ }
18423
18647
  return { systemPrompt: `${event.systemPrompt}
18424
18648
 
18425
18649
  ${injection}` };