@theokit/sdk 4.57.0 → 4.59.0

package/dist/internal/memory/storage/markdown-store.d.ts

@@ -1,5 +1,35 @@
 import { type MemoryConfig, type MemoryFact } from "../types.js";
 export declare function memoryDir(cwd: string): string;
+/**
+ * Where a NEW fact should be written.
+ *
+ * `.theokit/memory` by default, exactly as before. When the agent was given a `local.sessionDir`,
+ * it becomes `<sessionDir>/projects/<encoded-cwd>/memory` — the same place the transcript for that
+ * project goes, so a session and the memories recorded during it land beside each other.
+ *
+ * `local.sessionDir` is the switch because it is already the option this project documents for CLI
+ * interop: point it at `~/.claude` and the CLI can `--continue` a session this agent wrote. Someone
+ * who set it has said they share state with that CLI, and memory following is what the sentence
+ * already implied. It needs no new option, and nothing moves for anyone who never set it.
+ *
+ * Safe because of the rule this pairs with — WRITE ONE, READ ALL. {@link readFactsFromMarkdown}
+ * covers every 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.
+ */
+export declare function memoryWriteDir(cwd: string, sessionDir: string | undefined): string;
+/**
+ * Where the Claude Code CLI keeps THIS project's memories.
+ *
+ * `<claudeHome>/projects/<encoded-cwd>/memory` — the same `encodeProjectDir` scheme the transcripts
+ * already use, which is why no new encoding is invented here. `CLAUDE_CONFIG_DIR` names the home
+ * when set (the CLI's own variable); `~/.claude` otherwise.
+ *
+ * Read, never written. Writing here by default would relocate every existing consumer's memories,
+ * and an additive change must not move what is already on disk — so this is the direction that
+ * costs nothing: a memory the CLI wrote becomes visible, and a memory the SDK wrote stays where the
+ * SDK put it.
+ */
+export declare function claudeProjectMemoryDir(cwd: string): string;
 export declare function memoryMdPath(cwd: string): string;
 export declare function notesDir(cwd: string): string;
 /**
@@ -10,14 +40,14 @@ export declare function notesDir(cwd: string): string;
  * repositories, and the store's own header invites editing them by hand — a converged writer that
  * stopped reading them would delete what someone recorded, which is worse than the format it fixes.
  */
-export declare function readFactsFromMarkdown(cwd: string): Promise<MemoryFact[]>;
+export declare function readFactsFromMarkdown(cwd: string, sessionDir?: string): Promise<MemoryFact[]>;
 /**
  * Write a fact as its own memory file and point the `MEMORY.md` index at it. Atomic + serialized.
  *
  * `modified` is stamped HERE and never read from `fact`: a timestamp a caller can set is a
  * timestamp that can lie about when something was learned, and weighing recency is the point.
  */
-export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact): Promise<void>;
+export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string): Promise<void>;
 /** Configuration-aware accessors honoring the existing MemoryConfig contract. */
-export declare function readFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;
-export declare function appendFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;
+export declare function readFacts(cwd: string, config: MemoryConfig, memoryHome?: string): Promise<MemoryFact[]>;
+export declare function appendFact(cwd: string, config: MemoryConfig, fact: MemoryFact, memoryHome?: string): Promise<void>;

package/dist/internal/persistence/index.cjs

@@ -1,11 +1,12 @@
 'use strict';
 
 var chunkVTYY7XL5_cjs = require('../../chunk-VTYY7XL5.cjs');
-var chunkU2AC6JUP_cjs = require('../../chunk-U2AC6JUP.cjs');
+var chunkJ2UROOIG_cjs = require('../../chunk-J2UROOIG.cjs');
 var chunkSKXBJ2NU_cjs = require('../../chunk-SKXBJ2NU.cjs');
 var chunk2ADR2GSO_cjs = require('../../chunk-2ADR2GSO.cjs');
 var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
 var chunkI6TGFUCO_cjs = require('../../chunk-I6TGFUCO.cjs');
+var chunkAQO3NSRG_cjs = require('../../chunk-AQO3NSRG.cjs');
 require('../../chunk-K3FW2XZD.cjs');
 require('../../chunk-JTB5Q42C.cjs');
 require('../../chunk-NUKRL3I6.cjs');
@@ -40,29 +41,17 @@ Object.defineProperty(exports, "PersistenceSchema", {
   enumerable: true,
   get: function () { return chunkVTYY7XL5_cjs.PersistenceSchema; }
 });
-Object.defineProperty(exports, "displayTheokitHome", {
-  enumerable: true,
-  get: function () { return chunkU2AC6JUP_cjs.displayTheokitHome; }
-});
-Object.defineProperty(exports, "getProfilesRoot", {
-  enumerable: true,
-  get: function () { return chunkU2AC6JUP_cjs.getProfilesRoot; }
-});
-Object.defineProperty(exports, "getTheokitHome", {
-  enumerable: true,
-  get: function () { return chunkU2AC6JUP_cjs.getTheokitHome; }
-});
 Object.defineProperty(exports, "migrateSchema", {
   enumerable: true,
-  get: function () { return chunkU2AC6JUP_cjs.migrateSchema; }
+  get: function () { return chunkJ2UROOIG_cjs.migrateSchema; }
 });
 Object.defineProperty(exports, "readVersionedJson", {
   enumerable: true,
-  get: function () { return chunkU2AC6JUP_cjs.readVersionedJson; }
+  get: function () { return chunkJ2UROOIG_cjs.readVersionedJson; }
 });
 Object.defineProperty(exports, "writeVersionedJson", {
   enumerable: true,
-  get: function () { return chunkU2AC6JUP_cjs.writeVersionedJson; }
+  get: function () { return chunkJ2UROOIG_cjs.writeVersionedJson; }
 });
 Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,
@@ -120,6 +109,18 @@ Object.defineProperty(exports, "replaceFileAtomic", {
   enumerable: true,
   get: function () { return chunkI6TGFUCO_cjs.replaceFileAtomic; }
 });
+Object.defineProperty(exports, "displayTheokitHome", {
+  enumerable: true,
+  get: function () { return chunkAQO3NSRG_cjs.displayTheokitHome; }
+});
+Object.defineProperty(exports, "getProfilesRoot", {
+  enumerable: true,
+  get: function () { return chunkAQO3NSRG_cjs.getProfilesRoot; }
+});
+Object.defineProperty(exports, "getTheokitHome", {
+  enumerable: true,
+  get: function () { return chunkAQO3NSRG_cjs.getTheokitHome; }
+});
 exports.casUpdate = casUpdate;
 exports.createExclusive = createExclusive;
 //# sourceMappingURL=index.cjs.map

package/dist/internal/persistence/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":["open"],"mappings":";;;;;;;;;;;;;AAwDA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAMA,aAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACdO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.cjs","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call\n * created it, `false` when it was already there.\n *\n * The check and the create are one `open(path, \"wx\")` syscall, so of N processes racing to create\n * the same path exactly one gets `true` — no window between testing and writing. The content is\n * written after the create, so the `false` branch tells you the file exists, not that another\n * writer has finished filling it.\n *\n * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is\n * `ENOENT`, an unwritable one `EACCES`. This never creates directories.\n *\n * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is\n * subject to the process umask. That default is deliberate — the callers are token files,\n * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.\n *\n * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right\n * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential\n * exactly once. It cannot guard repeated updates, because a file that already exists always loses.\n * For read-modify-write on a path several writers touch, take a lock instead —\n * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For\n * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent\n * primitive.\n *\n * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets\n * ext4, APFS and NTFS.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,\n * and TypeScript scans EVERY leading comment range of the declaration that follows, including the\n * import right below this one. The tag that used to sit here deleted that import from the emitted\n * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint\n * (usetheodev/theokit-sdk#283 records the same trap on a declaration).\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Run an UPDATE and report whether it changed exactly the number of rows you expected — the\n * optimistic-concurrency equivalent of taking a lock.\n *\n * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the\n * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This\n * function generates nothing. It prepares the statement, runs it with `params`, and compares\n * `changes` against `expectedChanges` (default 1).\n *\n * `false` means the guard did not match — someone else moved the row first, or the id does not\n * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.\n * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with\n * whatever backoff it wants. There is no retry loop hidden in here, by design.\n *\n * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.\n * Only the row-count mismatch is reported as `false`.\n *\n * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap\n * the call yourself when the swap has to commit together with other writes.\n *\n * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser\n * finds out immediately and decides what to do. Prefer it when the contended state is already a\n * row with a version column. When the contended state is a FILE, there is no version column to\n * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is\n * to create something exactly once rather than update it, `createExclusive` is the primitive.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}
+{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":["open"],"mappings":";;;;;;;;;;;;;;AAwDA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAMA,aAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACdO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.cjs","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call\n * created it, `false` when it was already there.\n *\n * The check and the create are one `open(path, \"wx\")` syscall, so of N processes racing to create\n * the same path exactly one gets `true` — no window between testing and writing. The content is\n * written after the create, so the `false` branch tells you the file exists, not that another\n * writer has finished filling it.\n *\n * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is\n * `ENOENT`, an unwritable one `EACCES`. This never creates directories.\n *\n * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is\n * subject to the process umask. That default is deliberate — the callers are token files,\n * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.\n *\n * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right\n * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential\n * exactly once. It cannot guard repeated updates, because a file that already exists always loses.\n * For read-modify-write on a path several writers touch, take a lock instead —\n * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For\n * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent\n * primitive.\n *\n * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets\n * ext4, APFS and NTFS.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,\n * and TypeScript scans EVERY leading comment range of the declaration that follows, including the\n * import right below this one. The tag that used to sit here deleted that import from the emitted\n * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint\n * (usetheodev/theokit-sdk#283 records the same trap on a declaration).\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Run an UPDATE and report whether it changed exactly the number of rows you expected — the\n * optimistic-concurrency equivalent of taking a lock.\n *\n * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the\n * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This\n * function generates nothing. It prepares the statement, runs it with `params`, and compares\n * `changes` against `expectedChanges` (default 1).\n *\n * `false` means the guard did not match — someone else moved the row first, or the id does not\n * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.\n * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with\n * whatever backoff it wants. There is no retry loop hidden in here, by design.\n *\n * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.\n * Only the row-count mismatch is reported as `false`.\n *\n * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap\n * the call yourself when the swap has to commit together with other writes.\n *\n * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser\n * finds out immediately and decides what to do. Prefer it when the contended state is already a\n * row with a version column. When the contended state is a FILE, there is no version column to\n * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is\n * to create something exactly once rather than update it, `createExclusive` is the primitive.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}

package/dist/internal/persistence/index.js

@@ -1,9 +1,10 @@
 export { PersistenceSchema } from '../../chunk-HY66GLM6.js';
-export { displayTheokitHome, getProfilesRoot, getTheokitHome, migrateSchema, readVersionedJson, writeVersionedJson } from '../../chunk-UPRJR6IP.js';
+export { migrateSchema, readVersionedJson, writeVersionedJson } from '../../chunk-UCBJBJ27.js';
 export { applyWalWithFallback, containsCjk, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from '../../chunk-CQ2TQ32Y.js';
 export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-CV7XMBHP.js';
 export { withCwdMutex } from '../../chunk-Q5EWJPRY.js';
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-VF7EWVDG.js';
+export { displayTheokitHome, getProfilesRoot, getTheokitHome } from '../../chunk-UFLD2HEV.js';
 import '../../chunk-IDCKSLYH.js';
 import '../../chunk-T7XEKOVW.js';
 import '../../chunk-T7O6K6PX.js';

package/dist/internal/persistence/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":[],"mappings":";;;;;;;;;;;AAwDA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACdO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.js","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call\n * created it, `false` when it was already there.\n *\n * The check and the create are one `open(path, \"wx\")` syscall, so of N processes racing to create\n * the same path exactly one gets `true` — no window between testing and writing. The content is\n * written after the create, so the `false` branch tells you the file exists, not that another\n * writer has finished filling it.\n *\n * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is\n * `ENOENT`, an unwritable one `EACCES`. This never creates directories.\n *\n * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is\n * subject to the process umask. That default is deliberate — the callers are token files,\n * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.\n *\n * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right\n * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential\n * exactly once. It cannot guard repeated updates, because a file that already exists always loses.\n * For read-modify-write on a path several writers touch, take a lock instead —\n * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For\n * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent\n * primitive.\n *\n * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets\n * ext4, APFS and NTFS.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,\n * and TypeScript scans EVERY leading comment range of the declaration that follows, including the\n * import right below this one. The tag that used to sit here deleted that import from the emitted\n * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint\n * (usetheodev/theokit-sdk#283 records the same trap on a declaration).\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Run an UPDATE and report whether it changed exactly the number of rows you expected — the\n * optimistic-concurrency equivalent of taking a lock.\n *\n * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the\n * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This\n * function generates nothing. It prepares the statement, runs it with `params`, and compares\n * `changes` against `expectedChanges` (default 1).\n *\n * `false` means the guard did not match — someone else moved the row first, or the id does not\n * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.\n * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with\n * whatever backoff it wants. There is no retry loop hidden in here, by design.\n *\n * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.\n * Only the row-count mismatch is reported as `false`.\n *\n * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap\n * the call yourself when the swap has to commit together with other writes.\n *\n * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser\n * finds out immediately and decides what to do. Prefer it when the contended state is already a\n * row with a version column. When the contended state is a FILE, there is no version column to\n * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is\n * to create something exactly once rather than update it, `createExclusive` is the primitive.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}
+{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":[],"mappings":";;;;;;;;;;;;AAwDA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACdO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.js","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call\n * created it, `false` when it was already there.\n *\n * The check and the create are one `open(path, \"wx\")` syscall, so of N processes racing to create\n * the same path exactly one gets `true` — no window between testing and writing. The content is\n * written after the create, so the `false` branch tells you the file exists, not that another\n * writer has finished filling it.\n *\n * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is\n * `ENOENT`, an unwritable one `EACCES`. This never creates directories.\n *\n * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is\n * subject to the process umask. That default is deliberate — the callers are token files,\n * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.\n *\n * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right\n * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential\n * exactly once. It cannot guard repeated updates, because a file that already exists always loses.\n * For read-modify-write on a path several writers touch, take a lock instead —\n * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For\n * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent\n * primitive.\n *\n * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets\n * ext4, APFS and NTFS.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,\n * and TypeScript scans EVERY leading comment range of the declaration that follows, including the\n * import right below this one. The tag that used to sit here deleted that import from the emitted\n * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint\n * (usetheodev/theokit-sdk#283 records the same trap on a declaration).\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Run an UPDATE and report whether it changed exactly the number of rows you expected — the\n * optimistic-concurrency equivalent of taking a lock.\n *\n * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the\n * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This\n * function generates nothing. It prepares the statement, runs it with `params`, and compares\n * `changes` against `expectedChanges` (default 1).\n *\n * `false` means the guard did not match — someone else moved the row first, or the id does not\n * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.\n * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with\n * whatever backoff it wants. There is no retry loop hidden in here, by design.\n *\n * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.\n * Only the row-count mismatch is reported as `false`.\n *\n * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap\n * the call yourself when the swap has to commit together with other writes.\n *\n * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser\n * finds out immediately and decides what to do. Prefer it when the contended state is already a\n * row with a version column. When the contended state is a FILE, there is no version column to\n * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is\n * to create something exactly once rather than update it, `createExclusive` is the primitive.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}

package/dist/internal/persistence/paths.d.cts

@@ -48,6 +48,48 @@
  * declares in `exports` but does NOT cover with its semver contract.
  */
 export declare function getTheokitHome(cwd: string): string;
+/**
+ * Every directory a project's configuration may be read from, in precedence order.
+ *
+ * `.theokit` first, then `.claude`. The order is the whole contract: a project that declares a
+ * skill, agent or rule in both means the explicit namespace to win, and a caller merging these
+ * roots must therefore keep the FIRST occurrence of a name rather than the last.
+ *
+ * `.claude` is read because the formats already agree and only the location did not. Measured
+ * 2026-08-26: the SKILL.md frontmatter this SDK requires (`name` + `description`) is exactly what
+ * the CLI writes, its hook config is the same JSON shape, and 59 of the CLI's agent declarations
+ * parse here unchanged. A repository set up for the CLI was failing on the directory name alone.
+ *
+ * NOT a rename of `.theokit`, and not a migration. Both are read, so nothing that works today stops
+ * working — which is why this returns a LIST and not a single resolved answer.
+ *
+ * Deliberately NOT affected by `THEOKIT_HOME`, and this is the one thing to remember about it.
+ * That variable relocates cwd-anchored SDK *state* — sessions, the credential store. A project's
+ * *configuration* is a property of the repository, not of where this SDK keeps its state, and the
+ * loaders that read these directories have always anchored on `cwd` directly. Honouring the
+ * override here would silently move where a project's agents and skills come from, which is a
+ * behaviour change wearing the costume of a refactor.
+ *
+ * Creates nothing and checks nothing; either path may not exist, and the caller owns that.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function projectConfigRoots(cwd: string): string[];
+/**
+ * Every directory that may hold a plugin BUNDLE contributed by the Claude Code CLI.
+ *
+ * A CLI plugin is not a JS entry point — it is a folder whose `skills/` and `agents/` are what it
+ * exists to provide. Measured 2026-08-26 on an installed one: seven agents and three skills beside
+ * a manifest in `.claude-plugin/plugin.json`. Parsing that manifest and stopping there produced a
+ * plugin that loaded and did nothing.
+ *
+ * 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, not
+ * reading a project's configuration, and guessing at someone's enablement would run code they
+ * turned off.
+ */
+export declare function pluginBundleRoots(cwd: string): string[];
 /**
  * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
  *

package/dist/internal/persistence/paths.d.ts

@@ -48,6 +48,48 @@
  * declares in `exports` but does NOT cover with its semver contract.
  */
 export declare function getTheokitHome(cwd: string): string;
+/**
+ * Every directory a project's configuration may be read from, in precedence order.
+ *
+ * `.theokit` first, then `.claude`. The order is the whole contract: a project that declares a
+ * skill, agent or rule in both means the explicit namespace to win, and a caller merging these
+ * roots must therefore keep the FIRST occurrence of a name rather than the last.
+ *
+ * `.claude` is read because the formats already agree and only the location did not. Measured
+ * 2026-08-26: the SKILL.md frontmatter this SDK requires (`name` + `description`) is exactly what
+ * the CLI writes, its hook config is the same JSON shape, and 59 of the CLI's agent declarations
+ * parse here unchanged. A repository set up for the CLI was failing on the directory name alone.
+ *
+ * NOT a rename of `.theokit`, and not a migration. Both are read, so nothing that works today stops
+ * working — which is why this returns a LIST and not a single resolved answer.
+ *
+ * Deliberately NOT affected by `THEOKIT_HOME`, and this is the one thing to remember about it.
+ * That variable relocates cwd-anchored SDK *state* — sessions, the credential store. A project's
+ * *configuration* is a property of the repository, not of where this SDK keeps its state, and the
+ * loaders that read these directories have always anchored on `cwd` directly. Honouring the
+ * override here would silently move where a project's agents and skills come from, which is a
+ * behaviour change wearing the costume of a refactor.
+ *
+ * Creates nothing and checks nothing; either path may not exist, and the caller owns that.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function projectConfigRoots(cwd: string): string[];
+/**
+ * Every directory that may hold a plugin BUNDLE contributed by the Claude Code CLI.
+ *
+ * A CLI plugin is not a JS entry point — it is a folder whose `skills/` and `agents/` are what it
+ * exists to provide. Measured 2026-08-26 on an installed one: seven agents and three skills beside
+ * a manifest in `.claude-plugin/plugin.json`. Parsing that manifest and stopping there produced a
+ * plugin that loaded and did nothing.
+ *
+ * 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, not
+ * reading a project's configuration, and guessing at someone's enablement would run code they
+ * turned off.
+ */
+export declare function pluginBundleRoots(cwd: string): string[];
 /**
  * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
  *

package/dist/internal/persistence/session-dir.d.cts

@@ -1 +1,16 @@
+/** The subset of `LocalOptions` this resolver reads. */
+interface SessionDirOptions {
+    sessionDir?: string;
+    baseDir?: string;
+}
+/**
+ * The session directory the caller ASKED for, or `undefined` when they asked for nothing.
+ *
+ * {@link resolveSessionDir} always answers with a path, falling back to the default home — which is
+ * the right answer for "where do transcripts go" and the wrong one for "did this consumer opt into
+ * sharing state with the Claude Code CLI". Memory writes need the second question, and the two
+ * accepted names for the option live here, so asking it anywhere else would put a copy of that
+ * knowledge somewhere it can drift.
+ */
+export declare function explicitSessionDir(local: SessionDirOptions | undefined): string | undefined;
 export {};

package/dist/internal/persistence/session-dir.d.ts

@@ -1 +1,16 @@
+/** The subset of `LocalOptions` this resolver reads. */
+interface SessionDirOptions {
+    sessionDir?: string;
+    baseDir?: string;
+}
+/**
+ * The session directory the caller ASKED for, or `undefined` when they asked for nothing.
+ *
+ * {@link resolveSessionDir} always answers with a path, falling back to the default home — which is
+ * the right answer for "where do transcripts go" and the wrong one for "did this consumer opt into
+ * sharing state with the Claude Code CLI". Memory writes need the second question, and the two
+ * accepted names for the option live here, so asking it anywhere else would put a copy of that
+ * knowledge somewhere it can drift.
+ */
+export declare function explicitSessionDir(local: SessionDirOptions | undefined): string | undefined;
 export {};

package/dist/internal/runtime/memory/memory-store.d.ts

@@ -1,4 +1,4 @@
 import { type MemoryConfig, type MemoryFact, redactSecrets } from "../../memory/types.js";
 export { redactSecrets };
-export declare function readMemoryFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;
-export declare function appendMemoryFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;
+export declare function readMemoryFacts(cwd: string, config: MemoryConfig, memoryHome?: string): Promise<MemoryFact[]>;
+export declare function appendMemoryFact(cwd: string, config: MemoryConfig, fact: MemoryFact, memoryHome?: string): Promise<void>;

package/dist/internal/runtime/plugins/plugin-bundles.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Locating the plugin bundles a project carries.
+ *
+ * Shared by the skills and subagents loaders, which both need the same answer to "which folders in
+ * this project are plugins" and would otherwise each grow their own copy of the directory walk.
+ *
+ * @internal
+ */
+/**
+ * Every plugin folder under the project's plugin roots.
+ *
+ * Returns the FOLDERS, not their contents — what a bundle contributes (`skills/`, `agents/`) is the
+ * caller's business, and a loader that also knew the layout would have to change whenever the other
+ * one did.
+ *
+ * A missing root is not an error: most projects carry no plugins, and treating their absence as a
+ * failure would make "none installed" indistinguishable from "the directory could not be read".
+ */
+export declare function pluginBundleDirs(cwd: string): Promise<string[]>;

package/dist/project.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkZNW6V4Y6_cjs = require('./chunk-ZNW6V4Y6.cjs');
+var chunkLKFET5A3_cjs = require('./chunk-LKFET5A3.cjs');
 var chunkI6TGFUCO_cjs = require('./chunk-I6TGFUCO.cjs');
 var chunkK3FW2XZD_cjs = require('./chunk-K3FW2XZD.cjs');
 require('./chunk-JTB5Q42C.cjs');
@@ -12,7 +12,7 @@ var DEFAULT_FILENAME = "THEO.md";
 async function readProjectInstructions(cwd, options) {
   const filename = options?.filename ?? DEFAULT_FILENAME;
   const scope = options?.scope ?? "nearest";
-  const paths = chunkZNW6V4Y6_cjs.walkUpForFile(cwd, filename, options?.stopDir);
+  const paths = chunkLKFET5A3_cjs.walkUpForFile(cwd, filename, options?.stopDir);
   const files = [];
   for (const path of paths) {
     try {
@@ -31,7 +31,7 @@ function reduceContent(files, scope) {
 }
 async function writeProjectInstructions(cwd, content, options) {
   const filename = options?.filename ?? DEFAULT_FILENAME;
-  if (!chunkZNW6V4Y6_cjs.isSafePattern(filename)) {
+  if (!chunkLKFET5A3_cjs.isSafePattern(filename)) {
     throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `writeProjectInstructions: unsafe filename ${JSON.stringify(filename)} (no path traversal, separators, or absolute paths)`,
       { code: "unsafe_filename" }

package/dist/project.js

@@ -1,4 +1,4 @@
-import { walkUpForFile, isSafePattern } from './chunk-GTKFV7O5.js';
+import { walkUpForFile, isSafePattern } from './chunk-WFC26L6Y.js';
 import { replaceFileAtomic } from './chunk-VF7EWVDG.js';
 import { ConfigurationError } from './chunk-IDCKSLYH.js';
 import './chunk-T7XEKOVW.js';

package/dist/subagents-loader-6ATCDEKN.js

@@ -0,0 +1,8 @@
+export { loadSubagents } from './chunk-ZHPWGIUX.js';
+import './chunk-UFLD2HEV.js';
+import './chunk-AG5JPQIY.js';
+import './chunk-IDCKSLYH.js';
+import './chunk-T7XEKOVW.js';
+import './chunk-T7O6K6PX.js';
+//# sourceMappingURL=subagents-loader-6ATCDEKN.js.map
+//# sourceMappingURL=subagents-loader-6ATCDEKN.js.map

package/dist/{subagents-loader-J54ESLDV.js.map → subagents-loader-6ATCDEKN.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-J54ESLDV.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-6ATCDEKN.js"}

package/dist/subagents-loader-X5QKODCL.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+var chunkWNTAPVU5_cjs = require('./chunk-WNTAPVU5.cjs');
+require('./chunk-AQO3NSRG.cjs');
+require('./chunk-IWBGCBR6.cjs');
+require('./chunk-K3FW2XZD.cjs');
+require('./chunk-JTB5Q42C.cjs');
+require('./chunk-NUKRL3I6.cjs');
+
+
+
+Object.defineProperty(exports, "loadSubagents", {
+  enumerable: true,
+  get: function () { return chunkWNTAPVU5_cjs.loadSubagents; }
+});
+//# sourceMappingURL=subagents-loader-X5QKODCL.cjs.map
+//# sourceMappingURL=subagents-loader-X5QKODCL.cjs.map

package/dist/{subagents-loader-AZIXJ7D3.cjs.map → subagents-loader-X5QKODCL.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-AZIXJ7D3.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-X5QKODCL.cjs"}

package/dist/subagents-loader.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
-var chunkHJBMA5MB_cjs = require('./chunk-HJBMA5MB.cjs');
+var chunkWNTAPVU5_cjs = require('./chunk-WNTAPVU5.cjs');
+require('./chunk-AQO3NSRG.cjs');
 require('./chunk-IWBGCBR6.cjs');
 var chunkK3FW2XZD_cjs = require('./chunk-K3FW2XZD.cjs');
 require('./chunk-JTB5Q42C.cjs');
@@ -23,7 +24,7 @@ function resolveSources(options) {
 }
 async function discoverSubagents(cwd, options) {
   const sources = resolveSources(options);
-  return chunkHJBMA5MB_cjs.loadSubagents(cwd, sources.includes("project"), void 0);
+  return chunkWNTAPVU5_cjs.loadSubagents(cwd, sources.includes("project"), void 0);
 }
 async function loadSubagentDefinition(name, cwd, options) {
   return (await discoverSubagents(cwd, options))[name];

package/dist/subagents-loader.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/subagents-loader.ts"],"names":["ConfigurationError","loadSubagents"],"mappings":";;;;;;;;;AAuCA,IAAM,gBAAA,GAA8C,CAAC,SAAS,CAAA;AAgB9D,SAAS,eAAe,OAAA,EAA0E;AAChG,EAAA,MAAM,WAAW,OAAA,EAAS,cAAA;AAC1B,EAAA,IAAI,QAAA,KAAa,QAAW,OAAO,gBAAA;AACnC,EAAA,KAAA,MAAW,UAAU,QAAA,EAAU;AAC7B,IAAA,IAAI,CAAC,gBAAA,CAAiB,QAAA,CAAS,MAAM,CAAA,EAAG;AACtC,MAAA,MAAM,IAAIA,oCAAA;AAAA,QACR,CAAA,iCAAA,EAAoC,OAAO,MAAM,CAAC,gBAAgB,gBAAA,CAAiB,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,CAAA;AAAA,QAC7F,EAAE,MAAM,iCAAA;AAAkC,OAC5C;AAAA,IACF;AAAA,EACF;AACA,EAAA,OAAO,QAAA;AACT;AAOA,eAAsB,iBAAA,CACpB,KACA,OAAA,EAC0C;AAC1C,EAAA,MAAM,OAAA,GAAU,eAAe,OAAO,CAAA;AACtC,EAAA,OAAOC,gCAAc,GAAA,EAAK,OAAA,CAAQ,QAAA,CAAS,SAAS,GAAG,MAAS,CAAA;AAClE;AAQA,eAAsB,sBAAA,CACpB,IAAA,EACA,GAAA,EACA,OAAA,EACsC;AACtC,EAAA,OAAA,CAAQ,MAAM,iBAAA,CAAkB,GAAA,EAAK,OAAO,GAAG,IAAI,CAAA;AACrD","file":"subagents-loader.cjs","sourcesContent":["/**\n * M81 — `.theokit/agents` discovery, exposed so a consumer can read the on-disk subagent\n * definitions with one import instead of hand-rolling a second parser.\n *\n * ## Why this file exists\n *\n * `src/skills.ts` already exposed `discoverSkills` for the sibling domain. Subagents had the same\n * loader — `internal/runtime/skills/subagents-loader.ts` — with no public door. A consumer behind\n * the layer boundary (the agent-builder never imports `@theokit/sdk*` directly) could not reach it,\n * so re-implementing was the only legal option. It re-implemented, and then wrote a test whose only\n * job was to watch the two parsers for drift. That test is the cleanest possible evidence that the\n * duplication should not exist.\n *\n * ## What crosses is the PARSED config\n *\n * The return is `AgentDefinition` — already interpreted — never the `.md` text or the frontmatter\n * shape. Exporting the file format would freeze an internal detail as public API; exporting the\n * parsed value leaves the format free to change.\n */\n\nimport { ConfigurationError } from \"./errors.js\";\nimport { loadSubagents } from \"./internal/runtime/skills/subagents-loader.js\";\nimport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * The parsed subagent definition this module hands back.\n *\n * Re-exported here — beside the loader that produces it — so a consumer can NAME the value it\n * receives without reaching into `types/agent`, which no subpath publishes. A layer above may then\n * alias it (`AgentDefinition as SubagentDefinition`) to sidestep a name it has already spent.\n */\nexport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * Where subagent definitions may be read from. A closed union rather than a boolean: a third\n * source can join it without breaking the signature, and the call site reads as what it means.\n */\nexport type SubagentSource = \"project\";\n\nconst ACCEPTED_SOURCES: readonly SubagentSource[] = [\"project\"];\n\n/** Options for {@link discoverSubagents} / {@link loadSubagentDefinition}. */\nexport interface DiscoverSubagentsOptions {\n  /**\n   * Which sources to read. Defaults to `[\"project\"]` — `<cwd>/.theokit/agents/*.md`.\n   *\n   * An empty list reads NOTHING: the directory is never opened, so a caller that has not yet\n   * established trust in `cwd` can decline the read rather than filter its result.\n   */\n  readonly settingSources?: readonly SubagentSource[];\n}\n\n// Validated at the boundary (error-handling.md § 2): the union is erased at runtime, so a JS\n// caller — or a value crossing a serialization hop — can still carry a source nobody honors.\n// Dropping it silently would read as \"no subagents found\", which is the same shape as success.\nfunction resolveSources(options: DiscoverSubagentsOptions | undefined): readonly SubagentSource[] {\n  const declared = options?.settingSources;\n  if (declared === undefined) return ACCEPTED_SOURCES;\n  for (const source of declared) {\n    if (!ACCEPTED_SOURCES.includes(source)) {\n      throw new ConfigurationError(\n        `Unknown subagent setting source \"${String(source)}\" (accepted: ${ACCEPTED_SOURCES.join(\", \")})`,\n        { code: \"subagent_unknown_setting_source\" },\n      );\n    }\n  }\n  return declared;\n}\n\n/**\n * Discover the subagents defined under `<cwd>/.theokit/agents/*.md`.\n *\n * An absent directory yields `{}` — a project without subagents is the common case, not an error.\n */\nexport async function discoverSubagents(\n  cwd: string,\n  options?: DiscoverSubagentsOptions,\n): Promise<Record<string, AgentDefinition>> {\n  const sources = resolveSources(options);\n  return loadSubagents(cwd, sources.includes(\"project\"), undefined);\n}\n\n/**\n * Load ONE subagent definition by name, or `undefined` when it is not defined on disk.\n *\n * A thin selector over {@link discoverSubagents} rather than a second reader: one parser is the\n * whole point of this module.\n */\nexport async function loadSubagentDefinition(\n  name: string,\n  cwd: string,\n  options?: DiscoverSubagentsOptions,\n): Promise<AgentDefinition | undefined> {\n  return (await discoverSubagents(cwd, options))[name];\n}\n"]}
+{"version":3,"sources":["../src/subagents-loader.ts"],"names":["ConfigurationError","loadSubagents"],"mappings":";;;;;;;;;;AAuCA,IAAM,gBAAA,GAA8C,CAAC,SAAS,CAAA;AAgB9D,SAAS,eAAe,OAAA,EAA0E;AAChG,EAAA,MAAM,WAAW,OAAA,EAAS,cAAA;AAC1B,EAAA,IAAI,QAAA,KAAa,QAAW,OAAO,gBAAA;AACnC,EAAA,KAAA,MAAW,UAAU,QAAA,EAAU;AAC7B,IAAA,IAAI,CAAC,gBAAA,CAAiB,QAAA,CAAS,MAAM,CAAA,EAAG;AACtC,MAAA,MAAM,IAAIA,oCAAA;AAAA,QACR,CAAA,iCAAA,EAAoC,OAAO,MAAM,CAAC,gBAAgB,gBAAA,CAAiB,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,CAAA;AAAA,QAC7F,EAAE,MAAM,iCAAA;AAAkC,OAC5C;AAAA,IACF;AAAA,EACF;AACA,EAAA,OAAO,QAAA;AACT;AAOA,eAAsB,iBAAA,CACpB,KACA,OAAA,EAC0C;AAC1C,EAAA,MAAM,OAAA,GAAU,eAAe,OAAO,CAAA;AACtC,EAAA,OAAOC,gCAAc,GAAA,EAAK,OAAA,CAAQ,QAAA,CAAS,SAAS,GAAG,MAAS,CAAA;AAClE;AAQA,eAAsB,sBAAA,CACpB,IAAA,EACA,GAAA,EACA,OAAA,EACsC;AACtC,EAAA,OAAA,CAAQ,MAAM,iBAAA,CAAkB,GAAA,EAAK,OAAO,GAAG,IAAI,CAAA;AACrD","file":"subagents-loader.cjs","sourcesContent":["/**\n * M81 — `.theokit/agents` discovery, exposed so a consumer can read the on-disk subagent\n * definitions with one import instead of hand-rolling a second parser.\n *\n * ## Why this file exists\n *\n * `src/skills.ts` already exposed `discoverSkills` for the sibling domain. Subagents had the same\n * loader — `internal/runtime/skills/subagents-loader.ts` — with no public door. A consumer behind\n * the layer boundary (the agent-builder never imports `@theokit/sdk*` directly) could not reach it,\n * so re-implementing was the only legal option. It re-implemented, and then wrote a test whose only\n * job was to watch the two parsers for drift. That test is the cleanest possible evidence that the\n * duplication should not exist.\n *\n * ## What crosses is the PARSED config\n *\n * The return is `AgentDefinition` — already interpreted — never the `.md` text or the frontmatter\n * shape. Exporting the file format would freeze an internal detail as public API; exporting the\n * parsed value leaves the format free to change.\n */\n\nimport { ConfigurationError } from \"./errors.js\";\nimport { loadSubagents } from \"./internal/runtime/skills/subagents-loader.js\";\nimport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * The parsed subagent definition this module hands back.\n *\n * Re-exported here — beside the loader that produces it — so a consumer can NAME the value it\n * receives without reaching into `types/agent`, which no subpath publishes. A layer above may then\n * alias it (`AgentDefinition as SubagentDefinition`) to sidestep a name it has already spent.\n */\nexport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * Where subagent definitions may be read from. A closed union rather than a boolean: a third\n * source can join it without breaking the signature, and the call site reads as what it means.\n */\nexport type SubagentSource = \"project\";\n\nconst ACCEPTED_SOURCES: readonly SubagentSource[] = [\"project\"];\n\n/** Options for {@link discoverSubagents} / {@link loadSubagentDefinition}. */\nexport interface DiscoverSubagentsOptions {\n  /**\n   * Which sources to read. Defaults to `[\"project\"]` — `<cwd>/.theokit/agents/*.md`.\n   *\n   * An empty list reads NOTHING: the directory is never opened, so a caller that has not yet\n   * established trust in `cwd` can decline the read rather than filter its result.\n   */\n  readonly settingSources?: readonly SubagentSource[];\n}\n\n// Validated at the boundary (error-handling.md § 2): the union is erased at runtime, so a JS\n// caller — or a value crossing a serialization hop — can still carry a source nobody honors.\n// Dropping it silently would read as \"no subagents found\", which is the same shape as success.\nfunction resolveSources(options: DiscoverSubagentsOptions | undefined): readonly SubagentSource[] {\n  const declared = options?.settingSources;\n  if (declared === undefined) return ACCEPTED_SOURCES;\n  for (const source of declared) {\n    if (!ACCEPTED_SOURCES.includes(source)) {\n      throw new ConfigurationError(\n        `Unknown subagent setting source \"${String(source)}\" (accepted: ${ACCEPTED_SOURCES.join(\", \")})`,\n        { code: \"subagent_unknown_setting_source\" },\n      );\n    }\n  }\n  return declared;\n}\n\n/**\n * Discover the subagents defined under `<cwd>/.theokit/agents/*.md`.\n *\n * An absent directory yields `{}` — a project without subagents is the common case, not an error.\n */\nexport async function discoverSubagents(\n  cwd: string,\n  options?: DiscoverSubagentsOptions,\n): Promise<Record<string, AgentDefinition>> {\n  const sources = resolveSources(options);\n  return loadSubagents(cwd, sources.includes(\"project\"), undefined);\n}\n\n/**\n * Load ONE subagent definition by name, or `undefined` when it is not defined on disk.\n *\n * A thin selector over {@link discoverSubagents} rather than a second reader: one parser is the\n * whole point of this module.\n */\nexport async function loadSubagentDefinition(\n  name: string,\n  cwd: string,\n  options?: DiscoverSubagentsOptions,\n): Promise<AgentDefinition | undefined> {\n  return (await discoverSubagents(cwd, options))[name];\n}\n"]}

package/dist/subagents-loader.js

@@ -1,4 +1,5 @@
-import { loadSubagents } from './chunk-2QKTVKH3.js';
+import { loadSubagents } from './chunk-ZHPWGIUX.js';
+import './chunk-UFLD2HEV.js';
 import './chunk-AG5JPQIY.js';
 import { ConfigurationError } from './chunk-IDCKSLYH.js';
 import './chunk-T7XEKOVW.js';

package/dist/subagents-loader.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/subagents-loader.ts"],"names":[],"mappings":";;;;;;;AAuCA,IAAM,gBAAA,GAA8C,CAAC,SAAS,CAAA;AAgB9D,SAAS,eAAe,OAAA,EAA0E;AAChG,EAAA,MAAM,WAAW,OAAA,EAAS,cAAA;AAC1B,EAAA,IAAI,QAAA,KAAa,QAAW,OAAO,gBAAA;AACnC,EAAA,KAAA,MAAW,UAAU,QAAA,EAAU;AAC7B,IAAA,IAAI,CAAC,gBAAA,CAAiB,QAAA,CAAS,MAAM,CAAA,EAAG;AACtC,MAAA,MAAM,IAAI,kBAAA;AAAA,QACR,CAAA,iCAAA,EAAoC,OAAO,MAAM,CAAC,gBAAgB,gBAAA,CAAiB,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,CAAA;AAAA,QAC7F,EAAE,MAAM,iCAAA;AAAkC,OAC5C;AAAA,IACF;AAAA,EACF;AACA,EAAA,OAAO,QAAA;AACT;AAOA,eAAsB,iBAAA,CACpB,KACA,OAAA,EAC0C;AAC1C,EAAA,MAAM,OAAA,GAAU,eAAe,OAAO,CAAA;AACtC,EAAA,OAAO,cAAc,GAAA,EAAK,OAAA,CAAQ,QAAA,CAAS,SAAS,GAAG,MAAS,CAAA;AAClE;AAQA,eAAsB,sBAAA,CACpB,IAAA,EACA,GAAA,EACA,OAAA,EACsC;AACtC,EAAA,OAAA,CAAQ,MAAM,iBAAA,CAAkB,GAAA,EAAK,OAAO,GAAG,IAAI,CAAA;AACrD","file":"subagents-loader.js","sourcesContent":["/**\n * M81 — `.theokit/agents` discovery, exposed so a consumer can read the on-disk subagent\n * definitions with one import instead of hand-rolling a second parser.\n *\n * ## Why this file exists\n *\n * `src/skills.ts` already exposed `discoverSkills` for the sibling domain. Subagents had the same\n * loader — `internal/runtime/skills/subagents-loader.ts` — with no public door. A consumer behind\n * the layer boundary (the agent-builder never imports `@theokit/sdk*` directly) could not reach it,\n * so re-implementing was the only legal option. It re-implemented, and then wrote a test whose only\n * job was to watch the two parsers for drift. That test is the cleanest possible evidence that the\n * duplication should not exist.\n *\n * ## What crosses is the PARSED config\n *\n * The return is `AgentDefinition` — already interpreted — never the `.md` text or the frontmatter\n * shape. Exporting the file format would freeze an internal detail as public API; exporting the\n * parsed value leaves the format free to change.\n */\n\nimport { ConfigurationError } from \"./errors.js\";\nimport { loadSubagents } from \"./internal/runtime/skills/subagents-loader.js\";\nimport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * The parsed subagent definition this module hands back.\n *\n * Re-exported here — beside the loader that produces it — so a consumer can NAME the value it\n * receives without reaching into `types/agent`, which no subpath publishes. A layer above may then\n * alias it (`AgentDefinition as SubagentDefinition`) to sidestep a name it has already spent.\n */\nexport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * Where subagent definitions may be read from. A closed union rather than a boolean: a third\n * source can join it without breaking the signature, and the call site reads as what it means.\n */\nexport type SubagentSource = \"project\";\n\nconst ACCEPTED_SOURCES: readonly SubagentSource[] = [\"project\"];\n\n/** Options for {@link discoverSubagents} / {@link loadSubagentDefinition}. */\nexport interface DiscoverSubagentsOptions {\n  /**\n   * Which sources to read. Defaults to `[\"project\"]` — `<cwd>/.theokit/agents/*.md`.\n   *\n   * An empty list reads NOTHING: the directory is never opened, so a caller that has not yet\n   * established trust in `cwd` can decline the read rather than filter its result.\n   */\n  readonly settingSources?: readonly SubagentSource[];\n}\n\n// Validated at the boundary (error-handling.md § 2): the union is erased at runtime, so a JS\n// caller — or a value crossing a serialization hop — can still carry a source nobody honors.\n// Dropping it silently would read as \"no subagents found\", which is the same shape as success.\nfunction resolveSources(options: DiscoverSubagentsOptions | undefined): readonly SubagentSource[] {\n  const declared = options?.settingSources;\n  if (declared === undefined) return ACCEPTED_SOURCES;\n  for (const source of declared) {\n    if (!ACCEPTED_SOURCES.includes(source)) {\n      throw new ConfigurationError(\n        `Unknown subagent setting source \"${String(source)}\" (accepted: ${ACCEPTED_SOURCES.join(\", \")})`,\n        { code: \"subagent_unknown_setting_source\" },\n      );\n    }\n  }\n  return declared;\n}\n\n/**\n * Discover the subagents defined under `<cwd>/.theokit/agents/*.md`.\n *\n * An absent directory yields `{}` — a project without subagents is the common case, not an error.\n */\nexport async function discoverSubagents(\n  cwd: string,\n  options?: DiscoverSubagentsOptions,\n): Promise<Record<string, AgentDefinition>> {\n  const sources = resolveSources(options);\n  return loadSubagents(cwd, sources.includes(\"project\"), undefined);\n}\n\n/**\n * Load ONE subagent definition by name, or `undefined` when it is not defined on disk.\n *\n * A thin selector over {@link discoverSubagents} rather than a second reader: one parser is the\n * whole point of this module.\n */\nexport async function loadSubagentDefinition(\n  name: string,\n  cwd: string,\n  options?: DiscoverSubagentsOptions,\n): Promise<AgentDefinition | undefined> {\n  return (await discoverSubagents(cwd, options))[name];\n}\n"]}
+{"version":3,"sources":["../src/subagents-loader.ts"],"names":[],"mappings":";;;;;;;;AAuCA,IAAM,gBAAA,GAA8C,CAAC,SAAS,CAAA;AAgB9D,SAAS,eAAe,OAAA,EAA0E;AAChG,EAAA,MAAM,WAAW,OAAA,EAAS,cAAA;AAC1B,EAAA,IAAI,QAAA,KAAa,QAAW,OAAO,gBAAA;AACnC,EAAA,KAAA,MAAW,UAAU,QAAA,EAAU;AAC7B,IAAA,IAAI,CAAC,gBAAA,CAAiB,QAAA,CAAS,MAAM,CAAA,EAAG;AACtC,MAAA,MAAM,IAAI,kBAAA;AAAA,QACR,CAAA,iCAAA,EAAoC,OAAO,MAAM,CAAC,gBAAgB,gBAAA,CAAiB,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,CAAA;AAAA,QAC7F,EAAE,MAAM,iCAAA;AAAkC,OAC5C;AAAA,IACF;AAAA,EACF;AACA,EAAA,OAAO,QAAA;AACT;AAOA,eAAsB,iBAAA,CACpB,KACA,OAAA,EAC0C;AAC1C,EAAA,MAAM,OAAA,GAAU,eAAe,OAAO,CAAA;AACtC,EAAA,OAAO,cAAc,GAAA,EAAK,OAAA,CAAQ,QAAA,CAAS,SAAS,GAAG,MAAS,CAAA;AAClE;AAQA,eAAsB,sBAAA,CACpB,IAAA,EACA,GAAA,EACA,OAAA,EACsC;AACtC,EAAA,OAAA,CAAQ,MAAM,iBAAA,CAAkB,GAAA,EAAK,OAAO,GAAG,IAAI,CAAA;AACrD","file":"subagents-loader.js","sourcesContent":["/**\n * M81 — `.theokit/agents` discovery, exposed so a consumer can read the on-disk subagent\n * definitions with one import instead of hand-rolling a second parser.\n *\n * ## Why this file exists\n *\n * `src/skills.ts` already exposed `discoverSkills` for the sibling domain. Subagents had the same\n * loader — `internal/runtime/skills/subagents-loader.ts` — with no public door. A consumer behind\n * the layer boundary (the agent-builder never imports `@theokit/sdk*` directly) could not reach it,\n * so re-implementing was the only legal option. It re-implemented, and then wrote a test whose only\n * job was to watch the two parsers for drift. That test is the cleanest possible evidence that the\n * duplication should not exist.\n *\n * ## What crosses is the PARSED config\n *\n * The return is `AgentDefinition` — already interpreted — never the `.md` text or the frontmatter\n * shape. Exporting the file format would freeze an internal detail as public API; exporting the\n * parsed value leaves the format free to change.\n */\n\nimport { ConfigurationError } from \"./errors.js\";\nimport { loadSubagents } from \"./internal/runtime/skills/subagents-loader.js\";\nimport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * The parsed subagent definition this module hands back.\n *\n * Re-exported here — beside the loader that produces it — so a consumer can NAME the value it\n * receives without reaching into `types/agent`, which no subpath publishes. A layer above may then\n * alias it (`AgentDefinition as SubagentDefinition`) to sidestep a name it has already spent.\n */\nexport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * Where subagent definitions may be read from. A closed union rather than a boolean: a third\n * source can join it without breaking the signature, and the call site reads as what it means.\n */\nexport type SubagentSource = \"project\";\n\nconst ACCEPTED_SOURCES: readonly SubagentSource[] = [\"project\"];\n\n/** Options for {@link discoverSubagents} / {@link loadSubagentDefinition}. */\nexport interface DiscoverSubagentsOptions {\n  /**\n   * Which sources to read. Defaults to `[\"project\"]` — `<cwd>/.theokit/agents/*.md`.\n   *\n   * An empty list reads NOTHING: the directory is never opened, so a caller that has not yet\n   * established trust in `cwd` can decline the read rather than filter its result.\n   */\n  readonly settingSources?: readonly SubagentSource[];\n}\n\n// Validated at the boundary (error-handling.md § 2): the union is erased at runtime, so a JS\n// caller — or a value crossing a serialization hop — can still carry a source nobody honors.\n// Dropping it silently would read as \"no subagents found\", which is the same shape as success.\nfunction resolveSources(options: DiscoverSubagentsOptions | undefined): readonly SubagentSource[] {\n  const declared = options?.settingSources;\n  if (declared === undefined) return ACCEPTED_SOURCES;\n  for (const source of declared) {\n    if (!ACCEPTED_SOURCES.includes(source)) {\n      throw new ConfigurationError(\n        `Unknown subagent setting source \"${String(source)}\" (accepted: ${ACCEPTED_SOURCES.join(\", \")})`,\n        { code: \"subagent_unknown_setting_source\" },\n      );\n    }\n  }\n  return declared;\n}\n\n/**\n * Discover the subagents defined under `<cwd>/.theokit/agents/*.md`.\n *\n * An absent directory yields `{}` — a project without subagents is the common case, not an error.\n */\nexport async function discoverSubagents(\n  cwd: string,\n  options?: DiscoverSubagentsOptions,\n): Promise<Record<string, AgentDefinition>> {\n  const sources = resolveSources(options);\n  return loadSubagents(cwd, sources.includes(\"project\"), undefined);\n}\n\n/**\n * Load ONE subagent definition by name, or `undefined` when it is not defined on disk.\n *\n * A thin selector over {@link discoverSubagents} rather than a second reader: one parser is the\n * whole point of this module.\n */\nexport async function loadSubagentDefinition(\n  name: string,\n  cwd: string,\n  options?: DiscoverSubagentsOptions,\n): Promise<AgentDefinition | undefined> {\n  return (await discoverSubagents(cwd, options))[name];\n}\n"]}

package/docs/error-codes.md

@@ -34,7 +34,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cloud_custom_tools_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-agent.ts:123` +1 |
 | `cloud_incompatible_function_resolver` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-tool-parity.ts:43` +2 |
 | `cloud_incompatible_mcp_stdio_local` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-tool-parity.ts:74` |
-| `cloud_plugin_path_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:129` +1 |
+| `cloud_plugin_path_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:146` +1 |
 | `cloud_run_http_error` | domain | NetworkError | `packages/sdk/src/internal/cloud-agent/real-cloud-run.ts:155` |
 | `cloud_run_unknown_status` | domain | NetworkError | `packages/sdk/src/internal/cloud-agent/real-cloud-run.ts:284` +1 |
 | `cloud_runtime_pre_release` | domain | ConfigurationError | `packages/sdk/src/agent.ts:415` +2 |
@@ -69,10 +69,10 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `handoff_target_required` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:111` |
 | `hitl_timeout` | domain | HitlTimeoutError | `packages/sdk/src/internal/runtime/tools/hitl-middleware.ts:39` |
 | `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:429` |
-| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:189` |
-| `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:107` +2 |
-| `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:98` |
-| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:183` |
+| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:234` |
+| `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:152` +2 |
+| `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:143` |
+| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:228` |
 | `interactive_unavailable` | domain | InteractiveUnavailableError | `packages/sdk/src/interactive/types.ts:20` |
 | `INTERNAL_SERVER_ERROR` | domain | — | `packages/sdk/src/server/errors-envelope.ts:100` |
 | `invalid_argument` | domain | TheokitAgentError | `packages/sdk/src/compaction.ts:79` |
@@ -88,7 +88,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `invalid_input` | domain | MemoryAdapterError | `packages/memory-honcho/src/adapter.ts:98` +9 |
 | `invalid_max_iterations` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/real-local-run.ts:215` |
 | `invalid_memory_backend` | domain | ConfigurationError | `packages/sdk/src/internal/memory/index-manager-dispatch.ts:24` +1 |
-| `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:118` |
+| `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:184` |
 | `invalid_model_selection` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/model-selection.ts:21` |
 | `invalid_request` | transport | — | `packages/sdk/src/internal/error-mappers/vertex.ts:52` +1 |
 | `invalid_retry_config` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/retry/with-retry.ts:67` |
@@ -145,12 +145,12 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `personality_not_found` | domain | ConfigurationError | `packages/sdk/src/internal/personality/switch.ts:60` |
 | `personality_reserved_name` | domain | ConfigurationError | `packages/sdk/src/internal/personality/registry.ts:108` |
 | `pipeline_duplicate_provider` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/system-prompt/pipeline.ts:33` |
-| `plugin_entry_missing` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:104` |
+| `plugin_entry_missing` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:121` |
 | `plugin_frontmatter_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugin-frontmatter.ts:39` |
 | `plugin_late_register_kind` | domain | ConfigurationError | `packages/sdk/src/internal/plugins/manager.ts:103` |
-| `plugin_manifest_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:154` |
-| `plugin_manifest_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:160` |
-| `plugin_missing_manifest` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:145` +2 |
+| `plugin_manifest_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:171` |
+| `plugin_manifest_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:177` |
+| `plugin_missing_manifest` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugins/plugins-manager.ts:162` +2 |
 | `programmatic_hooks_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:97` |
 | `provider_unresolved` | domain | ConfigurationError | `packages/sdk/src/internal/llm/router.ts:99` +1 |
 | `quota_exceeded` | transport | — | `packages/sdk/src/errors.ts:0` |
@@ -175,13 +175,13 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `ssrf_blocked` | domain | — | `packages/sdk-tools/src/internal/network-guard.ts:23` |
 | `stream_idle_timeout` | domain | NetworkError | `packages/sdk/src/internal/llm/sse.ts:95` |
 | `stream_truncated` | domain | NetworkError | `packages/sdk/src/internal/llm/anthropic.ts:184` +1 |
-| `subagent_mcp_unsupported_local` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:111` |
+| `subagent_mcp_unsupported_local` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:165` |
 | `subagent_missing_description` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:142` |
-| `subagent_missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:183` |
+| `subagent_missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:242` |
 | `subagent_missing_prompt` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:147` |
-| `subagent_reasoning_effort_without_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:131` |
-| `subagent_sandbox_not_boolean` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:151` |
-| `subagent_unknown_field` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:96` |
+| `subagent_reasoning_effort_without_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:185` |
+| `subagent_sandbox_not_boolean` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:205` |
+| `subagent_unknown_field` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:150` |
 | `subagent_unknown_setting_source` | domain | ConfigurationError | `packages/sdk/src/subagents-loader.ts:61` |
 | `subscribe_baseUrl_missing` | domain | SubscriptionError | `packages/sdk/src/subscription/theokit-subscribe.ts:77` |
 | `subscribe_name_invalid` | domain | SubscriptionError | `packages/sdk/src/subscription/theokit-subscribe.ts:72` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.57.0",
+  "version": "4.59.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",