@theokit/sdk 4.57.0 → 4.59.0

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # Changelog
 
+## 4.59.0
+
+### Minor Changes
+
+- bd44344: Memories this SDK records can now land where the Claude Code CLI reads them, closing the direction
+  that was missing: the CLI's memories were already visible here, but everything this SDK wrote went to
+  `<cwd>/.theokit/memory`, invisible to the CLI in the same project.
+
+  `local.sessionDir` is the switch, because it is already the option this project documents for that
+  interop — point it at `~/.claude` and the CLI can `--continue` a session your agent wrote. A consumer
+  who set it has said they share state with that CLI, and memory following is what that sentence
+  already implied. There is no new option, and **nothing moves for anyone who never set it**.
+
+  The rule that makes this safe is **write one, read all**. Reads cover the project store, the
+  configured session home, and the CLI's own default location, so a consumer whose new facts move keeps
+  every fact they already had. The change relocates where the next one lands; it orphans nothing.
+
+  The `MEMORY.md` index is written beside the files it lists rather than in the project store — an
+  index in one directory naming memories in another points at files that are not there, and that index
+  is what the CLI reads.
+
+## 4.58.0
+
+### Minor Changes
+
+- b39bb5f: A plugin written for the Claude Code CLI now works instead of merely parsing.
+
+  Measured 2026-08-26 against an installed one: a CLI plugin is a BUNDLE — its manifest sits at
+  `<plugin>/.claude-plugin/plugin.json`, and what it exists to contribute are the `skills/` and
+  `agents/` directories beside it. This SDK's plugin concept is a JS `entry` point, so such a manifest
+  already parsed (zod strips the keys it does not know) and then did nothing at all: `name` and
+  `version` survived while the seven agents and three skills the plugin provides stayed invisible.
+
+  The manifest agreeing was never the point. Plugin folders under `.theokit/plugins` and
+  `.claude/plugins` now contribute their skills and agents, and the CLI's manifest location is read
+  without the deprecation warning that belongs to this SDK's own superseded `plugin.json` form —
+  telling someone to migrate a file that is canonical where it came from would be wrong.
+
+  Bundles are read AFTER the project's own directories, so a project can shadow a skill or an agent a
+  plugin ships without editing the plugin.
+
+  Project-scoped deliberately. The CLI also keeps plugins under `~/.claude/plugins/cache`, behind its
+  own installer and enable/disable state; reproducing that is an installation system rather than
+  reading a project's configuration, and guessing at someone's enablement would run code they had
+  turned off.
+
+- cb1ad68: A project set up for the Claude Code CLI now works without being converted: `.claude/agents`,
+  `.claude/skills`, `.claude/hooks.json` and the CLI's own `settings.json` / `settings.local.json` are
+  read alongside `.theokit`.
+
+  The formats already agreed — only the directory did not. Measured 2026-08-26: `SkillFrontmatter`
+  requires exactly the `name` and `description` the CLI writes into every `SKILL.md`; the hook config
+  this SDK parses is documented as, and is, the CLI's `settings.json` hooks shape; and 59 of the CLI's
+  agent declarations parse here unchanged.
+
+  `.theokit` is searched first and nothing about it changes. Two rules, and the difference between
+  them is deliberate:
+
+  - **Named declarations collide, so the first wins.** Two files declaring an agent or a skill called
+    `foo` are one name claimed twice, and the explicit namespace should win.
+  - **Hooks accumulate.** They are unnamed lists — two files declaring `PreToolUse` are two sets of
+    commands an operator wrote, and keeping one would drop the other in silence.
+
+  `THEOKIT_HOME` deliberately does not move these directories. It relocates cwd-anchored SDK _state_;
+  a project's _configuration_ belongs to the repository, and following the override here would change
+  where a project's agents come from under the cover of a refactor.
+
+  Known limitation: `SessionStart` and `PreCompact` have no firing point in this runtime, so hooks
+  declared for them are skipped with a warn rather than silently accepted. Four CLI events map:
+  `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`.
+
+- ad0c320: Rules and memories written for the Claude Code CLI are now read.
+
+  **Rules** — `.claude/rules/*.md` joins the discovery specs at priority 47. The format needed
+  nothing: measured over this repository's 32 rule files, none carries frontmatter, and the
+  `rules-frontmatter` parser already reads a file without it as `alwaysApply: true`. There was simply
+  no spec pointing at the directory.
+
+  47 rather than 46 because B-127 makes these numbers a public contract with room between adjacent
+  pairs for a consumer's own source. No published priority moves; a consumer that had chosen 47
+  collides, and that is the cost of an eighth default, recorded here rather than discovered later.
+
+  **Memories** — the CLI keeps a project's memories at `<claudeHome>/projects/<encoded-cwd>/memory/`,
+  the same encoding the transcripts use. `markdown-store`'s own header named that path as the target;
+  #389 converged the format and the ability to reach the directory was never built, so a memory the
+  CLI recorded was invisible to an agent working in the same repository. Both stores are read now,
+  `.theokit` first. `CLAUDE_CONFIG_DIR` names the home when set.
+
+  Reading only — writes still go to `.theokit/memory`. Writing elsewhere by default would relocate
+  every existing consumer's memories, which is the one thing an additive change must not do.
+
+  One fidelity fix came with it: a memory's BODY is the fact, and `description` is the one-line recall
+  aid. This SDK writes both the same, so nothing it wrote changes — but the CLI writes a summary above
+  the substance, and reading only the summary dropped the fact itself.
+
+- 78bff6c: `THEOKIT_DIR_NAME` no longer appears in `SOVEREIGN_ENV_KEYS`. It was documented there as naming the project config directory, and nothing ever read it — setting it did nothing. If you want the SDK to read configuration from `.claude` alongside `.theokit`, that now happens by default and needs no variable. `SOVEREIGN_ENV_KEYS` is public, so a consumer narrowing a type to it gains one fewer member.
+
+### Patch Changes
+
+- 5f3b1da: Agent files written for the Claude Code CLI now load.
+
+  Two defects, both measured against the 64 agent-directory files on one machine (a project
+  `.claude/agents` plus every installed plugin):
+
+  - **`color` made the file a load error.** It appeared in 38 of the 59 agent declarations — it is the
+    CLI's label colour and changes nothing about what an agent may do, but the loader rejects unknown
+    frontmatter fields, so a majority of real agent files could not be loaded at all.
+  - **One README stopped every agent in the directory.** A markdown file with no frontmatter threw
+    `subagent_missing_frontmatter`, aborting the whole directory read. `.claude/agents/README.md` is a
+    real file in this repository, cited by its own cycle rules.
+
+  The strict-field check is NOT loosened — its reason is sound, and stated where it lives: a dropped
+  `sandbox` that an operator wrote believing it confines the child is a silent gate. Fields known to be
+  inert for this runtime are now named explicitly, which is the difference between "we know this one
+  and it does nothing" and "we have never heard of this". A field that could change behaviour still
+  fails loudly, and a file that HAS frontmatter and gets it wrong is still a broken agent. Only the
+  no-frontmatter case is skipped, with a warn naming the file.
+
+  Measured after: 64 files in, 59 agents loaded, 5 documentation files skipped. Before: zero.
+
 ## 4.57.0
 
 ### Minor Changes

package/dist/{agent-ZIYCVEZL.js → agent-ST27RIJE.js}

@@ -1,7 +1,7 @@
-export { Agent } from './chunk-7TCRNXNK.js';
+export { Agent } from './chunk-7LOIUIQZ.js';
 import './chunk-WG7R5W6R.js';
-import './chunk-G6EEYRDD.js';
-import './chunk-YMA4S2WO.js';
+import './chunk-ZA255A62.js';
+import './chunk-MZ2FGBLZ.js';
 import './chunk-2SFBB54R.js';
 import './chunk-SUKXXLWD.js';
 import './chunk-K2BQQ445.js';
@@ -14,9 +14,9 @@ import './chunk-WTMU7J4U.js';
 import './chunk-5JLFFPCH.js';
 import './chunk-G24KZRSA.js';
 import './chunk-HKCKOAIO.js';
-import './chunk-7FHZ4VQX.js';
+import './chunk-SAVIWMZB.js';
 import './chunk-KVNWIAO4.js';
-import './chunk-UPRJR6IP.js';
+import './chunk-UCBJBJ27.js';
 import './chunk-FD2UT76F.js';
 import './chunk-4VPXM6UU.js';
 import './chunk-U54XCYG3.js';
@@ -24,7 +24,7 @@ import './chunk-NAF4L3T6.js';
 import './chunk-RNB4APBZ.js';
 import './chunk-6X6ID4MO.js';
 import './chunk-4ERPXIVB.js';
-import './chunk-GTKFV7O5.js';
+import './chunk-WFC26L6Y.js';
 import './chunk-7AD3ZTZL.js';
 import './chunk-QARJGQSA.js';
 import './chunk-RIAM53CP.js';
@@ -37,7 +37,8 @@ import './chunk-CV7XMBHP.js';
 import './chunk-Q5EWJPRY.js';
 import './chunk-RUDY2GTT.js';
 import './chunk-VF7EWVDG.js';
-import './chunk-2QKTVKH3.js';
+import './chunk-ZHPWGIUX.js';
+import './chunk-UFLD2HEV.js';
 import './chunk-AG5JPQIY.js';
 import './chunk-F7AQV62G.js';
 import './chunk-R7WIIPUR.js';
@@ -49,5 +50,5 @@ import './chunk-3OR54XG4.js';
 import './chunk-IDCKSLYH.js';
 import './chunk-T7XEKOVW.js';
 import './chunk-T7O6K6PX.js';
-//# sourceMappingURL=agent-ZIYCVEZL.js.map
-//# sourceMappingURL=agent-ZIYCVEZL.js.map
+//# sourceMappingURL=agent-ST27RIJE.js.map
+//# sourceMappingURL=agent-ST27RIJE.js.map

package/dist/{agent-ZIYCVEZL.js.map → agent-ST27RIJE.js.map}

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

package/dist/{agent-2T2EJIP6.cjs → agent-VHRX7XGW.cjs}

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkM2JWHKO6_cjs = require('./chunk-M2JWHKO6.cjs');
+var chunkSMUAG2DY_cjs = require('./chunk-SMUAG2DY.cjs');
 require('./chunk-KKK3FZ4A.cjs');
-require('./chunk-E7JHD6QJ.cjs');
-require('./chunk-53CBTBWO.cjs');
+require('./chunk-554J7UQH.cjs');
+require('./chunk-P6H23T43.cjs');
 require('./chunk-BV2MWEMV.cjs');
 require('./chunk-NGESVVJN.cjs');
 require('./chunk-BUUUWQMB.cjs');
@@ -16,9 +16,9 @@ require('./chunk-4OTIXDMU.cjs');
 require('./chunk-DQKERTND.cjs');
 require('./chunk-Z4BCLVTI.cjs');
 require('./chunk-2ZPEDVLM.cjs');
-require('./chunk-E3WZ6Y4H.cjs');
+require('./chunk-7BG5UH3T.cjs');
 require('./chunk-KRD3GQAA.cjs');
-require('./chunk-U2AC6JUP.cjs');
+require('./chunk-J2UROOIG.cjs');
 require('./chunk-MUUQ2WFJ.cjs');
 require('./chunk-WJVHMTKB.cjs');
 require('./chunk-6JSIEDKL.cjs');
@@ -26,7 +26,7 @@ require('./chunk-FRITRLZQ.cjs');
 require('./chunk-4O5TGQBW.cjs');
 require('./chunk-NINIJCHU.cjs');
 require('./chunk-3YJNUKYN.cjs');
-require('./chunk-ZNW6V4Y6.cjs');
+require('./chunk-LKFET5A3.cjs');
 require('./chunk-VJ26EKGJ.cjs');
 require('./chunk-R3UPQFKK.cjs');
 require('./chunk-VKJ7V7EB.cjs');
@@ -39,7 +39,8 @@ require('./chunk-2ADR2GSO.cjs');
 require('./chunk-ZF2LDKQQ.cjs');
 require('./chunk-2C72DXQF.cjs');
 require('./chunk-I6TGFUCO.cjs');
-require('./chunk-HJBMA5MB.cjs');
+require('./chunk-WNTAPVU5.cjs');
+require('./chunk-AQO3NSRG.cjs');
 require('./chunk-IWBGCBR6.cjs');
 require('./chunk-XSX2UU6Y.cjs');
 require('./chunk-3EE6LVWT.cjs');
@@ -56,7 +57,7 @@ require('./chunk-NUKRL3I6.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkM2JWHKO6_cjs.Agent; }
+  get: function () { return chunkSMUAG2DY_cjs.Agent; }
 });
-//# sourceMappingURL=agent-2T2EJIP6.cjs.map
-//# sourceMappingURL=agent-2T2EJIP6.cjs.map
+//# sourceMappingURL=agent-VHRX7XGW.cjs.map
+//# sourceMappingURL=agent-VHRX7XGW.cjs.map

package/dist/{agent-2T2EJIP6.cjs.map → agent-VHRX7XGW.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-2T2EJIP6.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-VHRX7XGW.cjs"}

package/dist/{chunk-E7JHD6QJ.cjs → chunk-554J7UQH.cjs}

@@ -3,6 +3,7 @@
 var chunkGHX4P3V2_cjs = require('./chunk-GHX4P3V2.cjs');
 var chunkKRD3GQAA_cjs = require('./chunk-KRD3GQAA.cjs');
 var chunkR3UPQFKK_cjs = require('./chunk-R3UPQFKK.cjs');
+var chunkBUIK7GUA_cjs = require('./chunk-BUIK7GUA.cjs');
 var chunkSKXBJ2NU_cjs = require('./chunk-SKXBJ2NU.cjs');
 var chunkZF2LDKQQ_cjs = require('./chunk-ZF2LDKQQ.cjs');
 var chunkI6TGFUCO_cjs = require('./chunk-I6TGFUCO.cjs');
@@ -13,6 +14,7 @@ var promises = require('fs/promises');
 var path = require('path');
 var fs = require('fs');
 var module$1 = require('module');
+var os = require('os');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 // src/internal/memory/escape-like-pattern.ts
@@ -78,7 +80,7 @@ function defaultIndexPath(cwd) {
 }
 function requireLance() {
   try {
-    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-E7JHD6QJ.cjs', document.baseURI).href)));
+    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-554J7UQH.cjs', document.baseURI).href)));
     return r("@lancedb/lancedb");
   } catch (cause) {
     throw new chunkK3FW2XZD_cjs.ConfigurationError(
@@ -366,23 +368,37 @@ var FACTS_HEADING = "## Facts";
 function memoryDir(cwd) {
   return path.join(cwd, ".theokit", "memory");
 }
+function memoryWriteDir(cwd, sessionDir) {
+  if (sessionDir === void 0 || sessionDir.trim().length === 0) return memoryDir(cwd);
+  return path.join(sessionDir, "projects", chunkBUIK7GUA_cjs.encodeProjectDir(cwd), "memory");
+}
+function claudeProjectMemoryDir(cwd) {
+  const home = process.env.CLAUDE_CONFIG_DIR?.trim();
+  const root = home !== void 0 && home.length > 0 ? home : path.join(os.homedir(), ".claude");
+  return path.join(root, "projects", chunkBUIK7GUA_cjs.encodeProjectDir(cwd), "memory");
+}
 function memoryMdPath(cwd) {
   return path.join(memoryDir(cwd), "MEMORY.md");
 }
 function notesDir(cwd) {
   return path.join(memoryDir(cwd), "notes");
 }
-async function readFactsFromMarkdown(cwd) {
-  let entries;
-  try {
-    entries = await promises.readdir(memoryDir(cwd));
-  } catch {
-    return [];
-  }
+async function readFactsFromMarkdown(cwd, sessionDir) {
   const facts = [];
-  for (const entry of entries.sort()) {
-    const fact = await readMemoryFileAt(cwd, entry);
-    if (fact !== void 0) facts.push(fact);
+  const roots = [
+    .../* @__PURE__ */ new Set([memoryDir(cwd), memoryWriteDir(cwd, sessionDir), claudeProjectMemoryDir(cwd)])
+  ];
+  for (const dir of roots) {
+    let entries;
+    try {
+      entries = await promises.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries.sort()) {
+      const fact = await readMemoryFileIn(dir, entry);
+      if (fact !== void 0) facts.push(fact);
+    }
   }
   try {
     facts.push(...parseFactsSection(await promises.readFile(memoryMdPath(cwd), "utf8")));
@@ -390,24 +406,25 @@ async function readFactsFromMarkdown(cwd) {
   }
   return facts;
 }
-async function readMemoryFileAt(cwd, entry) {
+async function readMemoryFileIn(dir, entry) {
   if (!entry.endsWith(".md") || entry === "MEMORY.md") return void 0;
   let raw;
   try {
-    raw = await promises.readFile(path.join(memoryDir(cwd), entry), "utf8");
+    raw = await promises.readFile(path.join(dir, entry), "utf8");
   } catch {
     return void 0;
   }
   const parsed = parseMemoryFile(raw);
   if (parsed === void 0) return void 0;
+  const body = parsed.body.trim();
   return {
-    text: parsed.description,
+    text: body.length > 0 ? body : parsed.description,
     ...parsed.kind !== void 0 ? { kind: parsed.kind } : {},
     ...parsed.modified !== void 0 ? { modified: parsed.modified } : {}
   };
 }
-function appendFactToMarkdown(cwd, fact) {
-  return chunkZF2LDKQQ_cjs.withCwdMutex(memoryDir(cwd), async () => {
+function appendFactToMarkdown(cwd, fact, targetDir = memoryDir(cwd)) {
+  return chunkZF2LDKQQ_cjs.withCwdMutex(targetDir, async () => {
     if (fact.kind !== void 0 && !MEMORY_KINDS.includes(fact.kind)) {
       throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `Unknown memory fact kind "${fact.kind}". Expected one of: ${MEMORY_KINDS.join(", ")}.`,
@@ -416,9 +433,9 @@ function appendFactToMarkdown(cwd, fact) {
     }
     const text = chunkJTB5Q42C_cjs.redactSecrets(fact.text);
     const name = slugForFact(text);
-    await promises.mkdir(memoryDir(cwd), { recursive: true });
+    await promises.mkdir(targetDir, { recursive: true });
     await chunkI6TGFUCO_cjs.replaceFileAtomic(
-      path.join(memoryDir(cwd), `${name}.md`),
+      path.join(targetDir, `${name}.md`),
       renderMemoryFile({
         name,
         description: text,
@@ -427,13 +444,13 @@ function appendFactToMarkdown(cwd, fact) {
         body: text
       })
     );
-    await chunkI6TGFUCO_cjs.replaceFileAtomic(memoryMdPath(cwd), await nextIndex(cwd, text, name));
+    await chunkI6TGFUCO_cjs.replaceFileAtomic(path.join(targetDir, "MEMORY.md"), await nextIndex(targetDir, text, name));
   });
 }
-async function nextIndex(cwd, text, name) {
+async function nextIndex(dir, text, name) {
   let existing = "";
   try {
-    existing = await promises.readFile(memoryMdPath(cwd), "utf8");
+    existing = await promises.readFile(path.join(dir, "MEMORY.md"), "utf8");
   } catch {
     existing = "";
   }
@@ -454,13 +471,13 @@ function parseFactsSection(raw) {
   const block = nextHeading === -1 ? tail : tail.slice(0, nextHeading);
   return block.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => line.slice(2).trim()).filter((body) => !INDEX_ENTRY.test(body)).map((body) => ({ text: body }));
 }
-async function readFacts(cwd, config) {
+async function readFacts(cwd, config, memoryHome) {
   if (!config.enabled) return [];
-  return readFactsFromMarkdown(cwd);
+  return readFactsFromMarkdown(cwd, memoryHome);
 }
-async function appendFact(cwd, config, fact) {
+async function appendFact(cwd, config, fact, memoryHome) {
   if (!config.enabled) return;
-  await appendFactToMarkdown(cwd, fact);
+  await appendFactToMarkdown(cwd, fact, memoryWriteDir(cwd, memoryHome));
 }
 var MAX_TURN_CHARS = 2e3;
 function sessionsDir(cwd) {
@@ -1061,5 +1078,5 @@ exports.openMemoryDb = openMemoryDb;
 exports.readFacts = readFacts;
 exports.readFactsFromMarkdown = readFactsFromMarkdown;
 exports.writeSessionSummary = writeSessionSummary;
-//# sourceMappingURL=chunk-E7JHD6QJ.cjs.map
-//# sourceMappingURL=chunk-E7JHD6QJ.cjs.map
+//# sourceMappingURL=chunk-554J7UQH.cjs.map
+//# sourceMappingURL=chunk-554J7UQH.cjs.map