@theokit/sdk 5.6.0 → 5.7.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 5.7.0
+
+### Minor Changes
+
+- [#675](https://github.com/usetheokit/theokit-sdk/pull/675) [`cbbed19`](https://github.com/usetheokit/theokit-sdk/commit/cbbed19abff45b58c10de1bf694524fbd246d6c2) Thanks [@usetheodev](https://github.com/usetheodev)! - A repo-root instruction file now requires a grant a consumer can write.
+  
+  `DEFAULT_DISCOVERY_SPECS` carries four repo-root instruction files whose bodies enter the system
+  prompt as if we had written them — `AGENTS.md`, `GEMINI.md`, `CLAUDE.md` and `.cursor/rules/*.mdc`.
+  Until now exactly ONE spec in that file carried a gate, and it was `.claude/rules/*.md`. A cloned
+  repository's `.claude/rules/*.md` needed a declaration; the `CLAUDE.md` one directory up did not,
+  while both carried the same risk.
+  
+  **The vocabulary landed before the gate, and the order is the whole point.** `CompatSource` went
+  from two literals to five:
+  
+  ```ts
+  compatSources: ["agents"]   // AGENTS.md is admitted; GEMINI.md is not
+  ```
+  
+  Gating the four against the OLD union would have gated three formats on a grant nobody could write
+  and made them permanently unreachable — worse than the gap. A test asserts the invariant in both
+  directions and fails the moment a spec is gated on a token the union does not carry.
+  
+  **Separate literals, not one `foreign` token**, so a consumer who wants `AGENTS.md` is not forced to
+  also admit `.cursor/rules/*.mdc`.
+  
+  **BREAKING for a consumer who declares nothing**: they went from four repo-root files in the prompt
+  to none. That is the intended behaviour and it is LOUD — `withheldSpecs` reports every withheld file
+  by path with the grant that restores it, and the runner warns once naming each one. A count would be
+  a diagnosis with no remedy: you cannot decide whether to grant a dialect without knowing which file
+  it brings.
+  
+  `undefined` and `[]` stay distinct: no gate configured admits everything, an empty declaration
+  withholds every gated spec. Collapsing them would restore the defect the first gate closed.
+
+- [#675](https://github.com/usetheokit/theokit-sdk/pull/675) [`de40d9f`](https://github.com/usetheokit/theokit-sdk/commit/de40d9f3d398f84d5b145cec8bc56a4c6ec85a25) Thanks [@usetheodev](https://github.com/usetheodev)! - The pre-compaction seam now reaches the compaction path a consumer actually calls.
+  
+  There are three compaction paths in this ecosystem. `withPreCompaction`, shipped in
+  `@theokit/agents@14.1.0`, covers one of them — the agents-layer strategy. The other two are
+  `autoCompactIfNeeded` and `Agent.compact(sessionId, { trigger })`, and **the second is the one a
+  person reaches**: `/compact` → `handleCompact` → `compactSession` → `Agent.compact`.
+  
+  ```ts
+  await Agent.compact(agentId, {
+    trigger: "manual",
+    onPreCompact: async ({ messages, trigger, signal }) => {
+      await archive(messages, { because: trigger })   // runs BEFORE the transcript is rewritten
+    },
+    onPreCompactError: (e) => report(e),              // compaction proceeds either way
+  })
+  ```
+  
+  **One seam covers both SDK paths** because they converge on `compactSessionTranscript`. A seam per
+  caller would need each one to choose, and a caller that chooses wrong reintroduces the gap.
+  
+  **`trigger` is received, not inferred.** It already existed in the options and already reached the
+  compaction boundary; the handler is simply told. Inferring it from the call site would be right today
+  and silently wrong the first time a third caller appears.
+  
+  **Failure never blocks compaction.** A handler that throws is reported; one that exceeds its bound is
+  abandoned with its `AbortSignal` aborted first, so it can stop rather than be left running. A hook
+  that could block would turn a consumer's bug into a runtime that cannot reclaim its context.
+  
+  **Nothing changes for a consumer who registers nothing** — the seam is not entered, asserted by a
+  test rather than left as an inference.
+
 ## 5.6.0
 
 ### Minor Changes

package/dist/{agent-G6g-uwcB.d.ts → agent-Bqzdhkqr.d.ts}

@@ -1046,7 +1046,7 @@ type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
  *
  * @public
  */
-type CompatSource = "claude-code" | "theokit" | CompatSourceAdapter;
+type CompatSource = "claude-code" | "theokit" | "agents" | "gemini" | "cursor" | CompatSourceAdapter;
 /**
  * A surface a foreign configuration source may be admitted to.
  *

package/dist/{agent-82d_DrCL.d.cts → agent-Dya5SmhY.d.cts}

@@ -1046,7 +1046,7 @@ type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
  *
  * @public
  */
-type CompatSource = "claude-code" | "theokit" | CompatSourceAdapter;
+type CompatSource = "claude-code" | "theokit" | "agents" | "gemini" | "cursor" | CompatSourceAdapter;
 /**
  * A surface a foreign configuration source may be admitted to.
  *

package/dist/{agent-JJZM2VIK.js → agent-EQ5HKTWV.js}

@@ -1,23 +1,24 @@
-export { Agent } from './chunk-2UXQASTX.js';
+export { Agent } from './chunk-FUUSIT2T.js';
 import './chunk-K2VMFZQ5.js';
-import './chunk-2QKV4CGK.js';
+import './chunk-CZWN4C6A.js';
 import './chunk-K2BQQ445.js';
-import './chunk-7MMTZBTT.js';
-import './chunk-N2KAIZ5D.js';
+import './chunk-P5S3WCSZ.js';
+import './chunk-DQNI52VV.js';
 import './chunk-2SFBB54R.js';
 import './chunk-55GB6JYQ.js';
 import './chunk-H73MEMQB.js';
 import './chunk-OR6XIWLB.js';
-import './chunk-BZ3YMAMP.js';
+import './chunk-R3LBRQAN.js';
 import './chunk-AAEZSPTC.js';
-import './chunk-KZSKIUXZ.js';
+import './chunk-N7VAE6DZ.js';
 import './chunk-UBR5PWD7.js';
 import './chunk-2XC6KDJM.js';
 import './chunk-XB4GI5RZ.js';
 import './chunk-24MGQDK3.js';
 import './chunk-2WXHA33T.js';
 import './chunk-HKCKOAIO.js';
-import './chunk-HUDNLFY4.js';
+import './chunk-3VXQEQE4.js';
+import './chunk-7C3HWGCW.js';
 import './chunk-KVNWIAO4.js';
 import './chunk-SVQIW5RJ.js';
 import './chunk-FD2UT76F.js';
@@ -27,7 +28,7 @@ import './chunk-NAF4L3T6.js';
 import './chunk-CFE6QF2Q.js';
 import './chunk-6X6ID4MO.js';
 import './chunk-CA5VUAP3.js';
-import './chunk-5NELQ6LB.js';
+import './chunk-A6PDYH55.js';
 import './chunk-SAGRF4IB.js';
 import './chunk-EH6XD3FY.js';
 import './chunk-UKMBRMGT.js';
@@ -54,5 +55,5 @@ import './chunk-V22DZIXO.js';
 import './chunk-NJWYQWDL.js';
 import './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';
-//# sourceMappingURL=agent-JJZM2VIK.js.map
-//# sourceMappingURL=agent-JJZM2VIK.js.map
+//# sourceMappingURL=agent-EQ5HKTWV.js.map
+//# sourceMappingURL=agent-EQ5HKTWV.js.map

package/dist/{agent-JJZM2VIK.js.map → agent-EQ5HKTWV.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-JJZM2VIK.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-EQ5HKTWV.js"}

package/dist/{agent-47NS6ZVL.cjs → agent-KA63WDQH.cjs}

@@ -1,25 +1,26 @@
 'use strict';
 
-var chunkGCHZMH42_cjs = require('./chunk-GCHZMH42.cjs');
+var chunkA575WPBL_cjs = require('./chunk-A575WPBL.cjs');
 require('./chunk-KVSAY6NZ.cjs');
-require('./chunk-DZG77WU7.cjs');
+require('./chunk-3XSWF5AP.cjs');
 require('./chunk-BUUUWQMB.cjs');
-require('./chunk-VUHXC74Q.cjs');
-require('./chunk-7IZKTQ5G.cjs');
+require('./chunk-33A27NFX.cjs');
+require('./chunk-YYN6BB7R.cjs');
 require('./chunk-BV2MWEMV.cjs');
 require('./chunk-D6POWE7E.cjs');
 require('./chunk-GHX4P3V2.cjs');
 require('./chunk-TMKTSYDS.cjs');
-require('./chunk-GFFBXSQT.cjs');
+require('./chunk-HNAYCTX4.cjs');
 require('./chunk-7FDKWDA2.cjs');
-require('./chunk-C4ZQPWXJ.cjs');
+require('./chunk-ZLMU5EU3.cjs');
 require('./chunk-FUSDYC2B.cjs');
 require('./chunk-YJNYDJ2T.cjs');
 require('./chunk-24SYBZPL.cjs');
 require('./chunk-QOGNZMHD.cjs');
 require('./chunk-YIFFF23U.cjs');
 require('./chunk-2ZPEDVLM.cjs');
-require('./chunk-EIOMN5VA.cjs');
+require('./chunk-EFETPSJZ.cjs');
+require('./chunk-GK3UG7YQ.cjs');
 require('./chunk-KRD3GQAA.cjs');
 require('./chunk-RQMCOFAI.cjs');
 require('./chunk-MUUQ2WFJ.cjs');
@@ -29,7 +30,7 @@ require('./chunk-FRITRLZQ.cjs');
 require('./chunk-NQTD6QOW.cjs');
 require('./chunk-NINIJCHU.cjs');
 require('./chunk-MYJGWS2J.cjs');
-require('./chunk-LD6HASA5.cjs');
+require('./chunk-7KBNBPFK.cjs');
 require('./chunk-IJ7M6GOG.cjs');
 require('./chunk-7A6535RA.cjs');
 require('./chunk-SA6K24NB.cjs');
@@ -61,7 +62,7 @@ require('./chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkGCHZMH42_cjs.Agent; }
+  get: function () { return chunkA575WPBL_cjs.Agent; }
 });
-//# sourceMappingURL=agent-47NS6ZVL.cjs.map
-//# sourceMappingURL=agent-47NS6ZVL.cjs.map
+//# sourceMappingURL=agent-KA63WDQH.cjs.map
+//# sourceMappingURL=agent-KA63WDQH.cjs.map

package/dist/{agent-47NS6ZVL.cjs.map → agent-KA63WDQH.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-47NS6ZVL.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-KA63WDQH.cjs"}

package/dist/agent.d.ts

@@ -219,6 +219,17 @@ export declare class Agent {
     static compact(agentId: string, options?: {
         trigger?: "manual" | "auto";
         summarize?: (messages: readonly import("./compaction.js").CompressibleMessage[]) => Promise<string>;
+        /**
+         * B-082 — work to run before the transcript is rewritten, on THIS path.
+         *
+         * `/compact` reaches here, and before this option the seam existed only on the agents-layer
+         * strategy, which this path never touches. The handler is awaited, bounded, and its failure is
+         * reported without stopping compaction — the same contract `withPreCompaction` carries, not a
+         * second one.
+         */
+        onPreCompact?: import("./internal/session/compact-session.js").PreCompactHandler;
+        onPreCompactError?: (error: unknown) => void;
+        preCompactTimeoutMs?: number;
     }): Promise<import("./internal/session/compact-session.js").CompactResult>;
     /**
      * M51 — inject a SYNTHETIC user+assistant pair into a LOCAL session's persisted transcript WITHOUT

package/dist/{chunk-VUHXC74Q.cjs → chunk-33A27NFX.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkGHX4P3V2_cjs = require('./chunk-GHX4P3V2.cjs');
-var chunkGFFBXSQT_cjs = require('./chunk-GFFBXSQT.cjs');
+var chunkHNAYCTX4_cjs = require('./chunk-HNAYCTX4.cjs');
 var chunkA4RAL2ER_cjs = require('./chunk-A4RAL2ER.cjs');
 var chunkJ7J7J2GN_cjs = require('./chunk-J7J7J2GN.cjs');
 var chunk6LHQPOMI_cjs = require('./chunk-6LHQPOMI.cjs');
@@ -86,13 +86,13 @@ function findWordBoundarySplit(text, maxChars) {
 
 // src/internal/memory/corpus-sync.ts
 async function syncCorpus(repo, memoryRoot) {
-  const files = await chunkGFFBXSQT_cjs.collectMarkdownFiles(memoryRoot);
+  const files = await chunkHNAYCTX4_cjs.collectMarkdownFiles(memoryRoot);
   const existingByPath = repo.filesByPath();
   let filesUpdated = 0;
   let chunksWritten = 0;
   for (const entry of files) {
     const raw = await promises.readFile(entry.absolutePath, "utf8");
-    const hash = chunkGFFBXSQT_cjs.sha256(raw);
+    const hash = chunkHNAYCTX4_cjs.sha256(raw);
     if (existingByPath.get(entry.absolutePath)?.hash === hash) continue;
     const stats = await promises.stat(entry.absolutePath);
     const fileId = repo.upsertFile({
@@ -156,7 +156,7 @@ var LanceMemoryAdapter = class {
       limit: maxResults * 2,
       ...options.sources !== void 0 ? { sources: options.sources } : {}
     });
-    return lanceHits.filter((h) => h.score >= minScore).slice(0, maxResults).map((h) => translateLanceHit(h, query, chunkGFFBXSQT_cjs.resolveWeights(options)));
+    return lanceHits.filter((h) => h.score >= minScore).slice(0, maxResults).map((h) => translateLanceHit(h, query, chunkHNAYCTX4_cjs.resolveWeights(options)));
   }
   status() {
     return {
@@ -211,7 +211,7 @@ async function openLanceIndex(opts) {
       { code: "lance_requires_embedding" }
     );
   }
-  const lance = await chunkGFFBXSQT_cjs.LanceIndex.open({
+  const lance = await chunkHNAYCTX4_cjs.LanceIndex.open({
     cwd: opts.cwd,
     embedding: opts.embedding,
     ...opts.filePath !== void 0 ? { storagePath: opts.filePath } : {}
@@ -414,9 +414,9 @@ var IndexManager = class _IndexManager {
   }
   /** Internal SQLite-path open. Renamed from previous public `open`. */
   static async openSqliteInternal(opts) {
-    const memoryRoot = opts.memoryRoot ?? chunkGFFBXSQT_cjs.resolveMemoryRoot(opts.cwd);
-    const filePath = opts.filePath ?? chunkGFFBXSQT_cjs.defaultIndexPath(chunkGFFBXSQT_cjs.memoryIndexRoot(opts.cwd, memoryRoot));
-    const db = await chunkGFFBXSQT_cjs.openMemoryDb({ filePath });
+    const memoryRoot = opts.memoryRoot ?? chunkHNAYCTX4_cjs.resolveMemoryRoot(opts.cwd);
+    const filePath = opts.filePath ?? chunkHNAYCTX4_cjs.defaultIndexPath(chunkHNAYCTX4_cjs.memoryIndexRoot(opts.cwd, memoryRoot));
+    const db = await chunkHNAYCTX4_cjs.openMemoryDb({ filePath });
     const manager = new _IndexManager(memoryRoot, db, opts.embedding);
     if (opts.embedding !== void 0) await manager.initVectorBackend(opts.embedding);
     return manager;
@@ -497,7 +497,7 @@ var IndexManager = class _IndexManager {
         endLine,
         score: textScore,
         textScore,
-        snippet: chunkGFFBXSQT_cjs.truncateSnippet(String(row.text ?? "")),
+        snippet: chunkHNAYCTX4_cjs.truncateSnippet(String(row.text ?? "")),
         source: String(row.source),
         citation: `${path}:${startLine}-${endLine}`,
         // sneak the chunk id through for the hybrid join below
@@ -525,7 +525,7 @@ var IndexManager = class _IndexManager {
         score: 0.5,
         // LIKE has no relevance score — use a neutral midpoint
         textScore: 0.5,
-        snippet: chunkGFFBXSQT_cjs.truncateSnippet(String(row.text ?? "")),
+        snippet: chunkHNAYCTX4_cjs.truncateSnippet(String(row.text ?? "")),
         source: String(row.source),
         citation: `${path}:${startLine}-${endLine}`,
         chunkId: Number(row.id)
@@ -548,10 +548,10 @@ var IndexManager = class _IndexManager {
     return out;
   }
   combineHybridScores(textHits, vectorHitsById, options) {
-    const weights = chunkGFFBXSQT_cjs.resolveWeights(options);
+    const weights = chunkHNAYCTX4_cjs.resolveWeights(options);
     const merged = this.mergeHits(textHits, vectorHitsById);
     const combined = [...merged.values()].map(
-      (hit) => chunkGFFBXSQT_cjs.blendScores(hit, vectorHitsById.get(hit.chunkId)?.vectorScore ?? 0, weights)
+      (hit) => chunkHNAYCTX4_cjs.blendScores(hit, vectorHitsById.get(hit.chunkId)?.vectorScore ?? 0, weights)
     );
     return combined.sort((a, b) => b.score - a.score);
   }
@@ -579,7 +579,7 @@ var IndexManager = class _IndexManager {
         endLine,
         score: 0,
         textScore: 0,
-        snippet: chunkGFFBXSQT_cjs.truncateSnippet(String(row.text ?? "")),
+        snippet: chunkHNAYCTX4_cjs.truncateSnippet(String(row.text ?? "")),
         source: String(row.source),
         citation: `${path}:${startLine}-${endLine}`
       };
@@ -591,5 +591,5 @@ var IndexManager = class _IndexManager {
 };
 
 exports.IndexManager = IndexManager;
-//# sourceMappingURL=chunk-VUHXC74Q.cjs.map
-//# sourceMappingURL=chunk-VUHXC74Q.cjs.map
+//# sourceMappingURL=chunk-33A27NFX.cjs.map
+//# sourceMappingURL=chunk-33A27NFX.cjs.map