@theokit/sdk 4.55.0 → 4.57.0

package/dist/{inject-session-WQGGMCQY.cjs → inject-session-MLCJMYDG.cjs}

@@ -1,18 +1,18 @@
 'use strict';
 
-var chunkV2UUGUY4_cjs = require('./chunk-V2UUGUY4.cjs');
+var chunkKKK3FZ4A_cjs = require('./chunk-KKK3FZ4A.cjs');
 var chunk4OTIXDMU_cjs = require('./chunk-4OTIXDMU.cjs');
-require('./chunk-CTCGWIUD.cjs');
-var chunkJHPGF3FP_cjs = require('./chunk-JHPGF3FP.cjs');
+require('./chunk-Z4BCLVTI.cjs');
+var chunkBUIK7GUA_cjs = require('./chunk-BUIK7GUA.cjs');
 require('./chunk-I6TGFUCO.cjs');
 require('./chunk-JTB5Q42C.cjs');
 require('./chunk-NUKRL3I6.cjs');
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
-  await chunkV2UUGUY4_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
+  await chunkKKK3FZ4A_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
     const prior = await opts.store.readRecords(opts.loc.agentId);
-    const transcript = chunkJHPGF3FP_cjs.SessionTranscript.fromRecords(prior, {
+    const transcript = chunkBUIK7GUA_cjs.SessionTranscript.fromRecords(prior, {
       cwd: opts.loc.cwd,
       sessionId: opts.sessionId,
       model: opts.loc.model ?? "unknown"
@@ -25,5 +25,5 @@ async function injectSessionTurn(opts) {
 }
 
 exports.injectSessionTurn = injectSessionTurn;
-//# sourceMappingURL=inject-session-WQGGMCQY.cjs.map
-//# sourceMappingURL=inject-session-WQGGMCQY.cjs.map
+//# sourceMappingURL=inject-session-MLCJMYDG.cjs.map
+//# sourceMappingURL=inject-session-MLCJMYDG.cjs.map

package/dist/{inject-session-WQGGMCQY.cjs.map → inject-session-MLCJMYDG.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-WQGGMCQY.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-MLCJMYDG.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/{inject-session-BJMJH5BX.js → inject-session-RBQZ45UM.js}

@@ -1,7 +1,7 @@
-import { enqueueSessionWrite } from './chunk-OHBIUXKM.js';
+import { enqueueSessionWrite } from './chunk-WG7R5W6R.js';
 import { invalidateSessionCache } from './chunk-WTMU7J4U.js';
-import './chunk-BMAZLQQ4.js';
-import { SessionTranscript } from './chunk-DZBSJX6J.js';
+import './chunk-G24KZRSA.js';
+import { SessionTranscript } from './chunk-FKMUFNQE.js';
 import './chunk-VF7EWVDG.js';
 import './chunk-T7XEKOVW.js';
 import './chunk-T7O6K6PX.js';
@@ -23,5 +23,5 @@ async function injectSessionTurn(opts) {
 }
 
 export { injectSessionTurn };
-//# sourceMappingURL=inject-session-BJMJH5BX.js.map
-//# sourceMappingURL=inject-session-BJMJH5BX.js.map
+//# sourceMappingURL=inject-session-RBQZ45UM.js.map
+//# sourceMappingURL=inject-session-RBQZ45UM.js.map

package/dist/{inject-session-BJMJH5BX.js.map → inject-session-RBQZ45UM.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-BJMJH5BX.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-RBQZ45UM.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

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

@@ -2,9 +2,21 @@ import { type MemoryConfig, type MemoryFact } from "../types.js";
 export declare function memoryDir(cwd: string): string;
 export declare function memoryMdPath(cwd: string): string;
 export declare function notesDir(cwd: string): string;
-/** Read facts from `MEMORY.md`'s `## Facts` section. Returns `[]` when missing. */
+/**
+ * Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in
+ * `MEMORY.md`. Returns `[]` when the directory does not exist.
+ *
+ * Reading both is not transitional politeness. Those bullets are already on disk in consumers'
+ * 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[]>;
-/** Append a fact to `MEMORY.md ## Facts`. Creates the section if missing. Atomic + serialized. */
+/**
+ * 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>;
 /** Configuration-aware accessors honoring the existing MemoryConfig contract. */
 export declare function readFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;

package/dist/internal/memory/storage/memory-file.d.ts

@@ -0,0 +1,54 @@
+/**
+ * One memory as a file, in the shape the Claude Code CLI reads.
+ *
+ * `@theokit/sdk` already writes native Claude Code `.jsonl` sessions — the README's differentiator
+ * is "point `local.sessionDir` at `~/.claude` and the Claude Code CLI can `--continue` a session
+ * your agent wrote". Memory had no such convergence: a fact was a bullet under `## Facts` with its
+ * kind in an HTML comment (#389), which that CLI reads as prose. Pointing a memory directory at
+ * `~/.claude/projects/<project>/memory/` produced nothing it could open.
+ *
+ * The contract here was measured against a real store rather than inferred from documentation. Of
+ * nine files, all nine carry `name`, `description` and `metadata.type`; six also carry
+ * `node_type`, `originSessionId` and `modified`, which the runtime stamps on write. So the minimum
+ * a reader must accept is the first three — refusing the rest would refuse memories the CLI itself
+ * accepts.
+ *
+ * `originSessionId` is deliberately not written. It identifies the session that learned the fact,
+ * and the append path has no session in scope; inventing one would be worse than omitting a field
+ * the format already treats as optional.
+ *
+ * @internal
+ */
+import { type MemoryKind } from "../types.js";
+/** The fields one memory file carries. */
+export interface MemoryFileFields {
+    /** Slug, and the file's basename. */
+    readonly name: string;
+    /** One-line summary — what the index shows and what recall ranks. */
+    readonly description: string;
+    /** `metadata.type`, absent when the file does not declare one this contract admits. */
+    readonly kind?: MemoryKind;
+    /** `metadata.modified`, an ISO 8601 instant stamped by whoever wrote the file. */
+    readonly modified?: string;
+    /** The markdown after the frontmatter. */
+    readonly body: string;
+}
+/**
+ * A readable, filesystem-safe slug for `text`.
+ *
+ * Readability is the goal — a directory of `h-3f2a…` files is a directory nobody browses — but it
+ * is not the floor. The text comes from whatever a caller learned, so anything that fails the safe
+ * grammar falls back to {@link safeFilenameForId}, which is total and always yields a valid
+ * component.
+ */
+export declare function slugForFact(text: string): string;
+/** Render one memory file. `description` is quoted so a colon in the text cannot break the block. */
+export declare function renderMemoryFile(fields: MemoryFileFields): string;
+/**
+ * Read one memory file, or `undefined` when the content is not one.
+ *
+ * `undefined` rather than a throw, and rather than a best-effort object: the directory holds
+ * hand-written notes and a `MEMORY.md` index alongside the memories, and turning any of those into
+ * a fact would put text into recall that nobody recorded as one.
+ */
+export declare function parseMemoryFile(raw: string): MemoryFileFields | undefined;

package/dist/internal/memory/types.d.ts

@@ -5,8 +5,36 @@ export interface MemoryConfig {
     scope?: "agent" | "user" | "team";
     storePath?: string;
 }
+/**
+ * What a fact IS, which is what decides whether it ages (#389).
+ *
+ * The four are the distinctions that matter for retention and recall: a preference stays true until
+ * the user changes their mind, a project fact goes stale when the code moves, a reference either
+ * resolves or 404s, and feedback records a correction that was given. Without them, recall ranks one
+ * undifferentiated corpus and pruning has no basis to prefer a durable fact over a transient one.
+ *
+ * A kind is never INFERRED. A wrong kind is worse than none, because it makes retention and recall
+ * confident about the wrong thing — so a fact whose author did not say stays untyped.
+ */
+export type MemoryKind = "user" | "feedback" | "project" | "reference";
+/** The four values {@link MemoryKind} admits, for runtime validation at the storage boundary. */
+export declare const MEMORY_KINDS: readonly MemoryKind[];
 export interface MemoryFact {
     text: string;
+    /**
+     * What this fact is (#389). Absent means untyped, which is what a hand-written bullet under
+     * `## Facts` stays — those files are already on disk in consumers' repositories and the store's
+     * own header invites editing them.
+     */
+    kind?: MemoryKind;
+    /**
+     * ISO 8601 instant this fact was last written, stamped BY THE SDK.
+     *
+     * Supplying it does nothing: a timestamp a caller can set is a timestamp that can lie about when
+     * something was learned, and the whole point is to weigh a note from this morning against one
+     * from four months ago. Absent on a fact written before this existed, or hand-added.
+     */
+    modified?: string;
 }
 export { redactSecrets } from "../security/index.js";
 /**

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

@@ -81,8 +81,47 @@ export declare function defaultBaseDir(): string;
  * paths without a leading tilde pass through untouched.
  */
 export declare function expandTilde(p: string): string;
-/** The `.jsonl` path for a session: `<baseDir>/projects/<encoded-cwd>/<safe-sessionId>.jsonl`. */
+/** Is this id already a canonical UUID, and therefore usable as a filename verbatim? */
+export declare function isSessionUuid(id: string): boolean;
+/**
+ * The transcript filename for an agent id — always a UUID.
+ *
+ * #400: the Claude Code CLI resumes a transcript ONLY when its basename is a UUID. Measured against
+ * CLI 2.1.236: `<uuid>.jsonl` resumes; `agent-<uuid>.jsonl` and `billing-bot.jsonl` are both ignored,
+ * with no error — the session simply is not offered. So a session written under a human-readable
+ * agent id was invisible to `claude --continue`, which is the interoperability this project claims
+ * as its difference from a proprietary session store.
+ *
+ * An id that is ALREADY a UUID passes through verbatim, so a transcript Claude Code wrote keeps its
+ * own name and the two directions stay symmetric. Anything else is derived with a UUIDv8, which is
+ * deterministic: the same agent id always yields the same filename, so nothing has to be persisted
+ * to map one back to the other.
+ *
+ * A DERIVED name is version 8 — RFC 9562's slot for a UUID whose bits come from an
+ * implementation-defined scheme, which is exactly what this is. The obvious alternative was v5, but
+ * RFC 4122 fixes v5's hash to SHA-1, and reaching for SHA-1 in 2026 means either shipping a weak
+ * primitive or arguing with every scanner that flags it, forever. v8 lets the hash be SHA-256 and
+ * lets the version nibble say honestly that this is our scheme rather than a standard one.
+ *
+ * There is no security claim here either way — no secret, no signature, and nothing an attacker
+ * gains by colliding two agent ids inside one consumer's own directory. The hash is a naming
+ * function. The point of preferring SHA-256 is not that SHA-1 was exploitable here; it is that a
+ * weak primitive in the tree costs a permanent argument with every scanner that sees it.
+ *
+ * The version nibble was measured, not assumed: CLI 2.1.236 resumes a v8-named transcript exactly as
+ * it does a v4 one.
+ */
+export declare function sessionUuidFor(id: string): string;
+/** The `.jsonl` path for a session: `<baseDir>/projects/<encoded-cwd>/<session-uuid>.jsonl`. */
 export declare function transcriptPath(baseDir: string, cwd: string, sessionId: string): string;
+/**
+ * The path this session used BEFORE #400 made transcript filenames UUIDs.
+ *
+ * Kept so an existing transcript is never orphaned: {@link FsSessionStore} prefers this file when it
+ * exists, so history written under the old scheme keeps accumulating in the same file instead of
+ * being silently abandoned for a fresh one under the new name.
+ */
+export declare function legacyTranscriptPath(baseDir: string, cwd: string, sessionId: string): string;
 /** Write records as one JSONL line each (atomic; parent dir created). Returns the path. */
 export declare function writeTranscript(path: string, records: readonly SessionRecord[]): Promise<string>;
 /** Parse a transcript `.jsonl` into records; a missing file yields `[]`; malformed lines are skipped. */

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

@@ -81,8 +81,47 @@ export declare function defaultBaseDir(): string;
  * paths without a leading tilde pass through untouched.
  */
 export declare function expandTilde(p: string): string;
-/** The `.jsonl` path for a session: `<baseDir>/projects/<encoded-cwd>/<safe-sessionId>.jsonl`. */
+/** Is this id already a canonical UUID, and therefore usable as a filename verbatim? */
+export declare function isSessionUuid(id: string): boolean;
+/**
+ * The transcript filename for an agent id — always a UUID.
+ *
+ * #400: the Claude Code CLI resumes a transcript ONLY when its basename is a UUID. Measured against
+ * CLI 2.1.236: `<uuid>.jsonl` resumes; `agent-<uuid>.jsonl` and `billing-bot.jsonl` are both ignored,
+ * with no error — the session simply is not offered. So a session written under a human-readable
+ * agent id was invisible to `claude --continue`, which is the interoperability this project claims
+ * as its difference from a proprietary session store.
+ *
+ * An id that is ALREADY a UUID passes through verbatim, so a transcript Claude Code wrote keeps its
+ * own name and the two directions stay symmetric. Anything else is derived with a UUIDv8, which is
+ * deterministic: the same agent id always yields the same filename, so nothing has to be persisted
+ * to map one back to the other.
+ *
+ * A DERIVED name is version 8 — RFC 9562's slot for a UUID whose bits come from an
+ * implementation-defined scheme, which is exactly what this is. The obvious alternative was v5, but
+ * RFC 4122 fixes v5's hash to SHA-1, and reaching for SHA-1 in 2026 means either shipping a weak
+ * primitive or arguing with every scanner that flags it, forever. v8 lets the hash be SHA-256 and
+ * lets the version nibble say honestly that this is our scheme rather than a standard one.
+ *
+ * There is no security claim here either way — no secret, no signature, and nothing an attacker
+ * gains by colliding two agent ids inside one consumer's own directory. The hash is a naming
+ * function. The point of preferring SHA-256 is not that SHA-1 was exploitable here; it is that a
+ * weak primitive in the tree costs a permanent argument with every scanner that sees it.
+ *
+ * The version nibble was measured, not assumed: CLI 2.1.236 resumes a v8-named transcript exactly as
+ * it does a v4 one.
+ */
+export declare function sessionUuidFor(id: string): string;
+/** The `.jsonl` path for a session: `<baseDir>/projects/<encoded-cwd>/<session-uuid>.jsonl`. */
 export declare function transcriptPath(baseDir: string, cwd: string, sessionId: string): string;
+/**
+ * The path this session used BEFORE #400 made transcript filenames UUIDs.
+ *
+ * Kept so an existing transcript is never orphaned: {@link FsSessionStore} prefers this file when it
+ * exists, so history written under the old scheme keeps accumulating in the same file instead of
+ * being silently abandoned for a fresh one under the new name.
+ */
+export declare function legacyTranscriptPath(baseDir: string, cwd: string, sessionId: string): string;
 /** Write records as one JSONL line each (atomic; parent dir created). Returns the path. */
 export declare function writeTranscript(path: string, records: readonly SessionRecord[]): Promise<string>;
 /** Parse a transcript `.jsonl` into records; a missing file yields `[]`; malformed lines are skipped. */

package/dist/persistence.cjs

@@ -2,7 +2,7 @@
 
 var chunkVTYY7XL5_cjs = require('./chunk-VTYY7XL5.cjs');
 var chunk4I55V454_cjs = require('./chunk-4I55V454.cjs');
-var chunkJHPGF3FP_cjs = require('./chunk-JHPGF3FP.cjs');
+var chunkBUIK7GUA_cjs = require('./chunk-BUIK7GUA.cjs');
 var chunkSKXBJ2NU_cjs = require('./chunk-SKXBJ2NU.cjs');
 var chunk2ADR2GSO_cjs = require('./chunk-2ADR2GSO.cjs');
 var chunkZF2LDKQQ_cjs = require('./chunk-ZF2LDKQQ.cjs');
@@ -114,15 +114,15 @@ Object.defineProperty(exports, "sessionHasWriter", {
 });
 Object.defineProperty(exports, "encodeProjectDir", {
   enumerable: true,
-  get: function () { return chunkJHPGF3FP_cjs.encodeProjectDir; }
+  get: function () { return chunkBUIK7GUA_cjs.encodeProjectDir; }
 });
 Object.defineProperty(exports, "transcriptPath", {
   enumerable: true,
-  get: function () { return chunkJHPGF3FP_cjs.transcriptPath; }
+  get: function () { return chunkBUIK7GUA_cjs.transcriptPath; }
 });
 Object.defineProperty(exports, "transcriptRoot", {
   enumerable: true,
-  get: function () { return chunkJHPGF3FP_cjs.transcriptRoot; }
+  get: function () { return chunkBUIK7GUA_cjs.transcriptRoot; }
 });
 Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,

package/dist/persistence.js

@@ -1,6 +1,6 @@
 export { PersistenceSchema } from './chunk-HY66GLM6.js';
 export { SessionBusyError, acquireSessionWriter, sessionHasWriter } from './chunk-44JAAH4X.js';
-export { encodeProjectDir, transcriptPath, transcriptRoot } from './chunk-DZBSJX6J.js';
+export { encodeProjectDir, transcriptPath, transcriptRoot } from './chunk-FKMUFNQE.js';
 export { applyWalWithFallback, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from './chunk-CQ2TQ32Y.js';
 export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from './chunk-CV7XMBHP.js';
 export { withCwdMutex } from './chunk-Q5EWJPRY.js';

package/dist/sandbox/index.cjs

@@ -154,7 +154,7 @@ var RET_EPERM = SECCOMP_RET_ERRNO | EPERM & 65535;
 var SECCOMP_RET_KILL_PROCESS = 2147483648;
 var AF_UNIX = 1;
 var ALWAYS_DENIED = [101, 310, 311, 425, 426, 427];
-var NETWORK_DENIED = [42, 43, 288, 49, 50, 52, 51, 48, 44, 307, 299, 55, 54];
+var NETWORK_DENIED = [42, 43, 288, 49, 50, 48, 44, 307, 299];
 var SOCKET_SYSCALLS = [41, 53];
 var stmt = (code, k) => ({ code, jt: 0, jf: 0, k });
 var jmp = (code, k, jt, jf) => ({ code, jt, jf, k });