@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/opencode2.js CHANGED
@@ -14823,13 +14823,13 @@ function isWithin(directory, configured) {
14823
14823
  function mapLookup(map3, directory) {
14824
14824
  const cwd = normalize(directory);
14825
14825
  let best;
14826
- for (const [dir, bank] of Object.entries(map3)) {
14826
+ for (const [dir, value] of Object.entries(map3)) {
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(config3, directory, sessionRoot = "") {
14835
14835
  const directories = [normalize(directory)];
@@ -14853,6 +14853,10 @@ function isOptedIn(config3, directory) {
14853
14853
  const pathMap = config3.mapPathToBank;
14854
14854
  return Boolean(pathMap && directories.some((candidate) => mapLookup(pathMap, candidate)));
14855
14855
  }
14856
+ function pathSection(config3, paths, directory) {
14857
+ if (!directory || !paths) return void 0;
14858
+ return lookupDirectories(config3, directory).map((candidate) => mapLookup(paths, candidate)).find((section) => section !== void 0);
14859
+ }
14856
14860
  function mappedBank(config3, directory, sessionRoot) {
14857
14861
  const pathMap = config3.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 });
@@ -17606,10 +17819,12 @@ function syncCompanionSkill(harness, opts = {}) {
17606
17819
  }
17607
17820
  function readPackagedSkill(srcDir = packagedSkillDir()) {
17608
17821
  try {
17609
- const raw = readFileSync5(join14(srcDir, "SKILL.md"), "utf8");
17822
+ const path = join15(srcDir, "SKILL.md");
17823
+ const raw = readFileSync5(path, "utf8");
17610
17824
  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
17611
17825
  return {
17612
17826
  location: srcDir,
17827
+ path,
17613
17828
  description: frontmatter ? /^description:\s*(.+)$/m.exec(frontmatter[1])?.[1] ?? "" : "",
17614
17829
  content: frontmatter ? raw.slice(frontmatter[0].length) : raw
17615
17830
  };
@@ -17633,15 +17848,15 @@ function brandWord() {
17633
17848
  }
17634
17849
 
17635
17850
  // src/core/legacy.ts
17636
- import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
17851
+ import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
17637
17852
  import { homedir as homedir8 } from "os";
17638
- import { join as join15, relative, isAbsolute as isAbsolute2 } from "path";
17853
+ import { join as join16, relative, isAbsolute as isAbsolute2 } from "path";
17639
17854
  var LEGACY_CLAUDE_PLUGIN = "hindsight-memory";
17640
- function detectLegacyClaudePlugin(cwd, claudeDir = join15(homedir8(), ".claude")) {
17641
- const registry3 = readJson(join15(claudeDir, "plugins", "installed_plugins.json"));
17855
+ function detectLegacyClaudePlugin(cwd, claudeDir = join16(homedir8(), ".claude")) {
17856
+ const registry3 = readJson(join16(claudeDir, "plugins", "installed_plugins.json"));
17642
17857
  const plugins = registry3?.plugins;
17643
17858
  if (!plugins || typeof plugins !== "object") return void 0;
17644
- const enabled = readJson(join15(claudeDir, "settings.json"))?.enabledPlugins;
17859
+ const enabled = readJson(join16(claudeDir, "settings.json"))?.enabledPlugins;
17645
17860
  for (const [key, raw] of Object.entries(plugins)) {
17646
17861
  if (key.split("@")[0] !== LEGACY_CLAUDE_PLUGIN) continue;
17647
17862
  if (enabled && enabled[key] === false) continue;
@@ -17672,9 +17887,9 @@ function legacyClaudePluginWarning(key) {
17672
17887
  // src/core/session-cache.ts
17673
17888
  import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync3, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
17674
17889
  import { tmpdir as tmpdir3 } from "os";
17675
- import { dirname as dirname9, join as join16 } from "path";
17890
+ import { dirname as dirname9, join as join17 } from "path";
17676
17891
  function sessionCacheFile(harness, sessionId) {
17677
- return join16(tmpdir3(), `hindsight-${harness}`, `${sessionId}.json`);
17892
+ return join17(tmpdir3(), `hindsight-${harness}`, `${sessionId}.json`);
17678
17893
  }
17679
17894
  function readSessionCache(cacheFile) {
17680
17895
  try {
@@ -17716,7 +17931,7 @@ async function gitSyncNote(args) {
17716
17931
  if (mode === "none" || cold) return void 0;
17717
17932
  const head = gitHeadSha(cwd);
17718
17933
  if (!head) return void 0;
17719
- const gitlogCurrent = await client.listDocumentIds(`gitlog-head:${head}`, "all_strict").then((s) => s.has(`gitlog:${repoNameOf(cwd)}`)).catch(() => void 0);
17934
+ const gitlogCurrent = await gitLogIsCurrent(client, cwd, head).catch(() => void 0);
17720
17935
  if (gitlogCurrent === void 0) return void 0;
17721
17936
  if (mode === "message") return gitlogCurrent ? "git in sync" : "catching up on new commits";
17722
17937
  const deepened = [...gitIds].filter((id) => id.startsWith("git:")).length;
@@ -17842,7 +18057,8 @@ async function buildSessionStartContext(args) {
17842
18057
  }
17843
18058
  }
17844
18059
  const additionalContext = buildKnowledgePreamble(pages, {
17845
- reflectOnNewGoals: cfg.autoInject !== "reflect"
18060
+ reflectOnNewGoals: cfg.autoInject !== "reflect",
18061
+ extra: cfg.toolGuideExtra
17846
18062
  });
17847
18063
  const deferInitialReflect = cold === true || pageListKnown && pages.length === 0;
17848
18064
  let gitNote;
@@ -17868,7 +18084,7 @@ ${legacyClaudePluginWarning(legacyPlugin)}`;
17868
18084
  }
17869
18085
 
17870
18086
  // src/core/hook.ts
17871
- import { existsSync as existsSync7, readFileSync as readFileSync10 } from "fs";
18087
+ import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
17872
18088
 
17873
18089
  // src/core/inject.ts
17874
18090
  function buildReflectQuery(prompt) {
@@ -17917,7 +18133,7 @@ If you VERIFY this memory is wrong or outdated (the code or facts contradict it)
17917
18133
  // src/core/turn-journal.ts
17918
18134
  import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync5, readFileSync as readFileSync9, statSync as statSync3 } from "fs";
17919
18135
  import { tmpdir as tmpdir4 } from "os";
17920
- import { dirname as dirname10, join as join17 } from "path";
18136
+ import { dirname as dirname10, join as join18 } from "path";
17921
18137
 
17922
18138
  // src/core/transcript-util.ts
17923
18139
  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;
@@ -17958,7 +18174,6 @@ function actionLine(tool2, input) {
17958
18174
  var JOURNAL_MAX_BYTES = 8 * 1024 * 1024;
17959
18175
 
17960
18176
  // src/core/hook.ts
17961
- var HOOK_FALLBACK_BUDGET_MS = 7e3;
17962
18177
  var HOOK_INJECT_ATTEMPTS = 2;
17963
18178
  function resolveInjection(got, attempts) {
17964
18179
  if (got != null) return got;
@@ -17986,8 +18201,8 @@ async function injectRecall(harness, prompt, client, timeoutMs, event, lead) {
17986
18201
  return void 0;
17987
18202
  }
17988
18203
  }
17989
- async function reflectFallback(harness, prompt, client) {
17990
- const deadline = Date.now() + HOOK_FALLBACK_BUDGET_MS;
18204
+ async function reflectFallback(harness, prompt, client, timeoutMs) {
18205
+ const deadline = Date.now() + timeoutMs;
17991
18206
  const remaining = () => Math.max(deadline - Date.now(), 1);
17992
18207
  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
17993
18208
  // other tools read, so renaming it would silently break them.
@@ -18012,7 +18227,7 @@ async function buildHookOutput(args) {
18012
18227
  harness,
18013
18228
  prompt,
18014
18229
  client,
18015
- HOOK_FALLBACK_BUDGET_MS,
18230
+ cfg.injectTimeoutMs,
18016
18231
  "inject_pages",
18017
18232
  PAGE_INJECT_LEAD
18018
18233
  );
@@ -18025,7 +18240,7 @@ async function buildHookOutput(args) {
18025
18240
  harness,
18026
18241
  prompt,
18027
18242
  client,
18028
- HOOK_FALLBACK_BUDGET_MS,
18243
+ cfg.injectTimeoutMs,
18029
18244
  "inject_recall",
18030
18245
  RECALL_INJECT_LEAD
18031
18246
  );
@@ -18067,7 +18282,7 @@ async function buildHookOutput(args) {
18067
18282
  query: prompt.slice(0, 80)
18068
18283
  });
18069
18284
  if (e instanceof ReflectError && e.fallbackEligible) {
18070
- fallback = await reflectFallback(harness, prompt, client);
18285
+ fallback = await reflectFallback(harness, prompt, client, cfg.injectTimeoutMs);
18071
18286
  if (fallback) reflectAnswer = fallback;
18072
18287
  }
18073
18288
  }
@@ -18100,7 +18315,12 @@ async function buildHookOutput(args) {
18100
18315
  const blocks = [];
18101
18316
  if (reflectAnswer && reflectRanThisTurn) blocks.push(buildSystemInjection(reflectAnswer));
18102
18317
  if (cadence > 0 && turns % cadence === 0) {
18103
- blocks.push(buildRosterRefresh(pages, { reflectOnNewGoals: cfg.autoInject !== "reflect" }));
18318
+ blocks.push(
18319
+ buildRosterRefresh(pages, {
18320
+ reflectOnNewGoals: cfg.autoInject !== "reflect",
18321
+ extra: cfg.toolGuideExtra
18322
+ })
18323
+ );
18104
18324
  }
18105
18325
  const kept = blocks.filter(Boolean);
18106
18326
  let notice;
@@ -18169,6 +18389,7 @@ var RuntimeCore = class {
18169
18389
  pageTrigger: buildPageTrigger(this.cfg),
18170
18390
  reflectTimeoutMs: this.cfg.reflectToolTimeoutMs,
18171
18391
  reflectBudget: this.cfg.reflectBudget,
18392
+ toolGuideExtra: this.cfg.toolGuideExtra,
18172
18393
  stampFor: () => buildRetainStamp(this.cfg, {
18173
18394
  directory: this.projectDir,
18174
18395
  harness: this.harness,
@@ -18236,7 +18457,8 @@ var RuntimeCore = class {
18236
18457
  if (turns === 1) {
18237
18458
  blocks.push(
18238
18459
  buildKnowledgePreamble(output.pages, {
18239
- reflectOnNewGoals: this.cfg.autoInject !== "reflect"
18460
+ reflectOnNewGoals: this.cfg.autoInject !== "reflect",
18461
+ extra: this.cfg.toolGuideExtra
18240
18462
  })
18241
18463
  );
18242
18464
  }