@theokit/sdk 4.0.2 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.1.0
+
+### Minor Changes
+
+- c4d410c: SE41 — pluggable `SessionStore` seam over the native transcript. A minimal, two-method public port (`SessionStore.readRecords(agentId)` / `appendRecords(agentId, records)`) over the native `SessionRecord` shape, injected via `local.sessionStore`, so an external store (Postgres / Redis / KV / durable object) can be the **primary store AND resume source** — restoring the serverless (ephemeral FS) and multi-host / multi-pod resume use case SE40 dropped when it removed `ConversationStorageAdapter`, WITHOUT reverting that removed ~10-method adapter. DEFAULTS to a shipped `FsSessionStore` that reads and append-writes the native Claude-shaped `.jsonl` transcript (the same file the Claude Code CLI can `--continue`), so omitting `sessionStore` is byte-identical to current behavior — zero consumer change. Resume works across a simulated cold start (`Agent.resume(agentId, { local: { sessionStore } })` rebuilds history via the native DAG reader over `await store.readRecords(agentId)`); append-only compaction (`compact_boundary`) flows through `appendRecords`. `readRecords` throwing on resume surfaces as a typed error (fail-fast — never a silent empty history that would drop the conversation). Additive and back-compat.
+
 ## 4.0.2
 
 ### Patch Changes

package/dist/a2a/index.cjs

@@ -3506,6 +3506,72 @@ var init_cloud_tool_parity = __esm({
     init_errors();
   }
 });
+
+// src/internal/persistence/file-lock.ts
+async function getProperLockfile() {
+  if (cached !== void 0) return cached;
+  try {
+    const mod = await import('proper-lockfile');
+    if (!validateLockModule(mod)) {
+      if (!warnedStructural) {
+        warnedStructural = true;
+        process.stderr.write(
+          "[theokit-sdk] proper-lockfile: imported module does NOT expose the expected `lock`/`unlock` API surface. This may indicate a supply-chain compromise or an incompatible major version. Falling back to in-process mutex (no cross-process safety). Reinstall with: pnpm add proper-lockfile@^11\n"
+        );
+      }
+      cached = null;
+      return cached;
+    }
+    cached = mod;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+function validateLockModule(mod) {
+  if (mod === null || mod === void 0 || typeof mod !== "object") return false;
+  const m = mod;
+  return typeof m.lock === "function" && typeof m.unlock === "function";
+}
+async function withFileLock(path, fn, options) {
+  const lib = await getProperLockfile();
+  if (lib === null) {
+    if (!warnedMissing) {
+      warnedMissing = true;
+      process.stderr.write(
+        "[theokit-sdk] proper-lockfile not installed; cross-process file lock unavailable. Install with: pnpm add proper-lockfile\n"
+      );
+    }
+    return withCwdMutex(`file-lock:${path}`, fn);
+  }
+  return withCwdMutex(`file-lock:${path}`, async () => {
+    const release = await lib.lock(path, {
+      // EC-1: companion lockfile, target path may not exist yet.
+      lockfilePath: `${path}.lock`,
+      realpath: false,
+      stale: 3e4,
+      retries: {
+        retries: 5,
+        factor: 1.5,
+        minTimeout: 100,
+        maxTimeout: 5e3
+      }
+    });
+    try {
+      return await fn();
+    } finally {
+      await release();
+    }
+  });
+}
+var cached, warnedMissing, warnedStructural;
+var init_file_lock = __esm({
+  "src/internal/persistence/file-lock.ts"() {
+    init_cwd_mutex();
+    warnedMissing = false;
+    warnedStructural = false;
+  }
+});
 function encodeProjectDir(cwd) {
   return cwd.replace(/[^a-zA-Z0-9]/g, "-");
 }
@@ -3732,70 +3798,31 @@ var init_session_transcript = __esm({
     };
   }
 });
-
-// src/internal/persistence/file-lock.ts
-async function getProperLockfile() {
-  if (cached !== void 0) return cached;
-  try {
-    const mod = await import('proper-lockfile');
-    if (!validateLockModule(mod)) {
-      if (!warnedStructural) {
-        warnedStructural = true;
-        process.stderr.write(
-          "[theokit-sdk] proper-lockfile: imported module does NOT expose the expected `lock`/`unlock` API surface. This may indicate a supply-chain compromise or an incompatible major version. Falling back to in-process mutex (no cross-process safety). Reinstall with: pnpm add proper-lockfile@^11\n"
-        );
-      }
-      cached = null;
-      return cached;
-    }
-    cached = mod;
-  } catch {
-    cached = null;
-  }
-  return cached;
-}
-function validateLockModule(mod) {
-  if (mod === null || mod === void 0 || typeof mod !== "object") return false;
-  const m = mod;
-  return typeof m.lock === "function" && typeof m.unlock === "function";
-}
-async function withFileLock(path, fn, options) {
-  const lib = await getProperLockfile();
-  if (lib === null) {
-    if (!warnedMissing) {
-      warnedMissing = true;
-      process.stderr.write(
-        "[theokit-sdk] proper-lockfile not installed; cross-process file lock unavailable. Install with: pnpm add proper-lockfile\n"
-      );
-    }
-    return withCwdMutex(`file-lock:${path}`, fn);
-  }
-  return withCwdMutex(`file-lock:${path}`, async () => {
-    const release = await lib.lock(path, {
-      // EC-1: companion lockfile, target path may not exist yet.
-      lockfilePath: `${path}.lock`,
-      realpath: false,
-      stale: 3e4,
-      retries: {
-        retries: 5,
-        factor: 1.5,
-        minTimeout: 100,
-        maxTimeout: 5e3
+var FsSessionStore;
+var init_fs_session_store = __esm({
+  "src/internal/persistence/fs-session-store.ts"() {
+    init_file_lock();
+    init_session_transcript();
+    FsSessionStore = class {
+      #baseDir;
+      #cwd;
+      constructor(options) {
+        this.#baseDir = options.baseDir;
+        this.#cwd = options.cwd;
+      }
+      async readRecords(agentId) {
+        return readTranscript(transcriptPath(this.#baseDir, this.#cwd, agentId));
+      }
+      async appendRecords(agentId, records) {
+        if (records.length === 0) return;
+        const path$1 = transcriptPath(this.#baseDir, this.#cwd, agentId);
+        await promises.mkdir(path.dirname(path$1), { recursive: true });
+        await withFileLock(path$1, async () => {
+          const prior = await readTranscript(path$1);
+          await writeTranscript(path$1, [...prior, ...records]);
+        });
       }
-    });
-    try {
-      return await fn();
-    } finally {
-      await release();
-    }
-  });
-}
-var cached, warnedMissing, warnedStructural;
-var init_file_lock = __esm({
-  "src/internal/persistence/file-lock.ts"() {
-    init_cwd_mutex();
-    warnedMissing = false;
-    warnedStructural = false;
+    };
   }
 });
 function getTheokitHome(cwd) {
@@ -5127,6 +5154,8 @@ var init_memory_path_selector = __esm({
     PORT_MEMORY_PATH_ENV_VAR = "THEOKIT_PORT_MEMORY_PATH";
   }
 });
+
+// src/internal/runtime/session/agent-session-store.ts
 function seedTranscript(prior, opts) {
   return SessionTranscript.fromRecords(prior, opts);
 }
@@ -5164,8 +5193,8 @@ function appendConversation(transcript, conversation) {
     if (toolResults.length > 0) transcript.appendToolResults(toolResults);
   }
 }
-async function readSessionMessages(baseDir, cwd, agentId) {
-  const records = await readTranscript(transcriptPath(baseDir, cwd, agentId));
+async function readSessionMessages(store, agentId) {
+  const records = await store.readRecords(agentId);
   return reconstructMessages(records).map(narrowToSessionMessage);
 }
 function partToText(p) {
@@ -5182,37 +5211,31 @@ function narrowToSessionMessage(m) {
   const text = m.content.map(partToText).filter((s) => s.length > 0).join("\n");
   return { role, text };
 }
-async function persistTurn(loc, sessionId, turn) {
-  const path$1 = transcriptPath(loc.baseDir, loc.cwd, loc.agentId);
-  await promises.mkdir(path.dirname(path$1), { recursive: true });
-  await withFileLock(path$1, async () => {
-    const prior = await readTranscript(path$1);
-    const transcript = seedTranscript(prior, { cwd: loc.cwd, sessionId, model: loc.model });
-    transcript.appendUserTurn(turn.userText);
-    appendConversation(transcript, turn.conversation);
-    await writeTranscript(path$1, transcript.records());
-  });
+function deltaRecords(transcript, priorLength) {
+  return transcript.records().slice(priorLength);
 }
-async function appendCompactBoundaryRecord(loc, sessionId, meta) {
-  const path$1 = transcriptPath(loc.baseDir, loc.cwd, loc.agentId);
-  await promises.mkdir(path.dirname(path$1), { recursive: true });
-  await withFileLock(path$1, async () => {
-    const prior = await readTranscript(path$1);
-    const transcript = seedTranscript(prior, { cwd: loc.cwd, sessionId, model: loc.model });
-    transcript.appendCompactBoundary(meta);
-    await writeTranscript(path$1, transcript.records());
-  });
+async function persistTurn(store, loc, sessionId, turn) {
+  const prior = await store.readRecords(loc.agentId);
+  const transcript = seedTranscript(prior, { cwd: loc.cwd, sessionId, model: loc.model });
+  transcript.appendUserTurn(turn.userText);
+  appendConversation(transcript, turn.conversation);
+  await store.appendRecords(loc.agentId, deltaRecords(transcript, prior.length));
+}
+async function appendCompactBoundaryRecord(store, loc, sessionId, meta) {
+  const prior = await store.readRecords(loc.agentId);
+  const transcript = seedTranscript(prior, { cwd: loc.cwd, sessionId, model: loc.model });
+  transcript.appendCompactBoundary(meta);
+  await store.appendRecords(loc.agentId, deltaRecords(transcript, prior.length));
 }
 var init_agent_session_store = __esm({
   "src/internal/runtime/session/agent-session-store.ts"() {
-    init_file_lock();
     init_session_transcript();
   }
 });
 
 // src/internal/runtime/session/agent-session.ts
-function transcriptKey(baseDir, cwd, agentId) {
-  return `${baseDir}::${cwd}::${agentId}`;
+function transcriptKey(cwd, agentId) {
+  return `${cwd}::${agentId}`;
 }
 function appendSessionMessage(agentId, message) {
   const existing = sessions.get(agentId) ?? [];
@@ -5222,15 +5245,15 @@ function appendSessionMessage(agentId, message) {
 function getSessionMessages(agentId) {
   return sessions.get(agentId) ?? [];
 }
-function persistTurnToTranscript(loc, sessionId, turn, onCompact) {
-  const key = transcriptKey(loc.baseDir, loc.cwd, loc.agentId);
+function persistTurnToTranscript(store, loc, sessionId, turn, onCompact) {
+  const key = transcriptKey(loc.cwd, loc.agentId);
   const chained = (pendingWrites.get(key) ?? Promise.resolve()).then(async () => {
     try {
-      await persistTurn(loc, sessionId, turn);
+      await persistTurn(store, loc, sessionId, turn);
       const count = (recordCounts.get(key) ?? 0) + 1;
       recordCounts.set(key, count);
       if (count % COMPACTION_CHECK_INTERVAL === 0) {
-        await appendCompactBoundaryRecord(loc, sessionId, {
+        await appendCompactBoundaryRecord(store, loc, sessionId, {
           preTokens: 0,
           trigger: "auto"
         });
@@ -5253,10 +5276,10 @@ function persistTurnToTranscript(loc, sessionId, turn, onCompact) {
   );
 }
 async function hydrateSession(agentId, loc) {
-  const key = transcriptKey(loc.baseDir, loc.cwd, agentId);
+  const key = transcriptKey(loc.cwd, agentId);
   if (hydratedKeys.has(key)) return;
   hydratedKeys.add(key);
-  const persisted = await readSessionMessages(loc.baseDir, loc.cwd, agentId);
+  const persisted = await readSessionMessages(loc.store, agentId);
   if (persisted.length === 0) return;
   if (!sessions.has(agentId) || sessions.get(agentId)?.length === 0) {
     sessions.set(agentId, persisted);
@@ -5291,7 +5314,7 @@ async function runPostRunLifecycle(inputs) {
     userText,
     agentId,
     workspaceCwd,
-    baseDir,
+    sessionStore,
     model,
     onRunEvent,
     hooksExecutor,
@@ -5310,7 +5333,8 @@ async function runPostRunLifecycle(inputs) {
   }
   const conversation = await safeConversation(run);
   persistTurnToTranscript(
-    { baseDir, cwd: workspaceCwd, agentId, model },
+    sessionStore,
+    { cwd: workspaceCwd, agentId, model },
     agentId,
     { userText, conversation },
     onRunEvent !== void 0 ? () => emitRunEvent(onRunEvent, { type: "compact_boundary", trigger: "auto" }) : void 0
@@ -17758,6 +17782,7 @@ var init_local_agent = __esm({
     init_errors();
     init_ids();
     init_cwd_mutex();
+    init_fs_session_store();
     init_session_transcript();
     init_store();
     init_manager();
@@ -17801,6 +17826,12 @@ var init_local_agent = __esm({
        * `~/.theokit`; set `local.baseDir: "~/.claude"` for Claude Code CLI interop.
        */
       transcriptBaseDir;
+      /**
+       * SE41 — the session record store. Defaults to the FS transcript store (byte-
+       * identical to SE40); `local.sessionStore` injects an external store (Postgres /
+       * Redis / KV) so resume works on serverless (ephemeral FS) and multi-host.
+       */
+      sessionStore;
       /**
        * D319: lifecycle AbortController fired on `dispose()`. Composed with the
        * caller's `SendOptions.signal` via `anySignal` so the LLM `fetch()`
@@ -17843,6 +17874,7 @@ var init_local_agent = __esm({
         this.options = options;
         this.workspaceCwd = resolveCwd(options.local?.cwd);
         this.transcriptBaseDir = resolveBaseDir(options.local?.baseDir);
+        this.sessionStore = options.local?.sessionStore ?? new FsSessionStore({ baseDir: this.transcriptBaseDir, cwd: this.workspaceCwd });
         this.settingSourcesIncludeProject = includesSetting(options, "project");
         this.settingSourcesIncludePlugins = includesSetting(options, "plugins");
         const sub = bootstrapSubmanagers({
@@ -17890,7 +17922,7 @@ var init_local_agent = __esm({
           this.settingSourcesIncludeProject,
           this.options.agents
         );
-        await hydrateSession(this.agentId, { baseDir: this.transcriptBaseDir, cwd: this.workspaceCwd });
+        await hydrateSession(this.agentId, { store: this.sessionStore, cwd: this.workspaceCwd });
         await this.personalityStore.hydrate(this.agentId);
       }
       /** T4.2 — expose PluginManager so agent-loop can fire pre_tool_call hooks. @internal */
@@ -17946,7 +17978,7 @@ var init_local_agent = __esm({
             userText,
             agentId: this.agentId,
             workspaceCwd: this.workspaceCwd,
-            baseDir: this.transcriptBaseDir,
+            sessionStore: this.sessionStore,
             model: this.model?.id ?? "unknown",
             ...options.onRunEvent !== void 0 ? { onRunEvent: options.onRunEvent } : {},
             hooksExecutor: this.hooksExecutor,