@theokit/sdk 4.0.2 → 4.1.0

package/dist/{cron-L5QTlAtl.d.ts → cron-AzT5D0VP.d.ts}

@@ -626,6 +626,84 @@ declare class Skill {
     static create(spec: CreateSkillSpec): InlineSkill;
 }
 
+/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
+interface SessionRecord {
+    type: "user" | "assistant" | "system";
+    uuid: string;
+    parentUuid: string | null;
+    sessionId: string;
+    timestamp: string;
+    isSidechain?: boolean;
+    userType?: string;
+    cwd?: string;
+    version?: string;
+    subtype?: string;
+    compactMetadata?: {
+        preTokens: number;
+        trigger: string;
+    };
+    message?: Record<string, unknown>;
+}
+
+/**
+ * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
+ *
+ * A minimal, two-method port so an external store (Postgres / Redis / KV /
+ * durable object) can be the **primary store AND resume source** — the
+ * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
+ * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
+ * NOT that removed ~10-method adapter: the seam is JUST record read/append over
+ * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
+ * delete / objective methods).
+ *
+ * The SDK ships a real default implementation, `FsSessionStore`, that reads and
+ * append-writes the native Claude-shaped `.jsonl` transcript — omitting
+ * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
+ * consumer change). Injected via `local.sessionStore` for external stores.
+ *
+ * Consistency contract: `appendRecords` is append-only and ordering-preserving.
+ * The FS default serializes appends per agent with a cross-process file lock;
+ * external implementations own (and MUST document) their own concurrency
+ * guarantees for two hosts appending to the same `agentId`.
+ *
+ * @public
+ */
+
+/**
+ * The pluggable session-store seam. Exactly two methods over the native
+ * {@link SessionRecord} shape.
+ *
+ * @public
+ */
+interface SessionStore {
+    /**
+     * Return every persisted record for `agentId`, in append order. A session
+     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
+     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
+     * records via the native DAG reader, so the shape MUST be the exact
+     * {@link SessionRecord} the SDK writes.
+     *
+     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
+     * MUST throw a typed error rather than silently returning `[]` — a silent
+     * empty read would masquerade as "no history" and drop the conversation.
+     */
+    readRecords(agentId: string): Promise<SessionRecord[]>;
+    /**
+     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
+     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
+     * format is an append-only `parentUuid` DAG (compaction is a new-root
+     * `compact_boundary` record, still an append).
+     *
+     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
+     * is never blocked by store I/O — an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write). An external store that
+     * must guarantee durability should make `appendRecords` resilient (retry /
+     * durable write) internally. This differs from {@link SessionStore.readRecords},
+     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
+     */
+    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+}
+
 /**
  * Context manager backend.
  *
@@ -989,6 +1067,16 @@ interface LocalOptions {
      * Set to `~/.claude` to write sessions the Claude Code CLI can `--continue`.
      */
     baseDir?: string;
+    /**
+     * SE41 — inject an external {@link import("./session-store.js").SessionStore}
+     * (Postgres / Redis / KV / durable object) as the PRIMARY session store and
+     * resume source. Omit for the default FS transcript store (`baseDir` above) —
+     * byte-identical to SE40. Use this for serverless (ephemeral FS) or multi-host /
+     * multi-pod deployments where a resumed agent must read its history from a shared
+     * store instead of local disk. The records stay the native Claude-shaped shape,
+     * so `--continue` interop is preserved (a store may also mirror to `~/.claude`).
+     */
+    sessionStore?: SessionStore;
 }
 /**
  * Repo to clone into a cloud agent's VM.
@@ -2442,4 +2530,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type GoalOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type ContextBudget as D, type ContextManagerKind as E, type ContextSnapshot as F, type GetAgentOptions as G, type ContextSource as H, type InlineSkill as I, type ContextSourceStatus as J, type CreateSkillSpec as K, type LocalOptions as L, type MemorySettings as M, Cron as N, type CronCreateOptions as O, type ProviderRoutingSettings as P, type CronGetOptions as Q, type CronJob as R, type SystemPromptResolver as S, type CronJobStatus as T, type CronListOptions as U, type CronOperationOptions as V, type CronRunOptions as W, type CronRuntime as X, type CronSchedulerStatus as Y, type CronStartOptions as Z, type GoalEvent as _, type AgentDefinition as a, type GoalResult as a0, type HookName as a1, type InvalidateCacheOptions as a2, type MemoryAdapter as a3, type MemoryAdapterCapabilities as a4, type MemoryContext as a5, type MemoryFact as a6, type MemoryProviderHandle as a7, type MemoryProviderInitOptions as a8, type MemoryRevision as a9, type SystemPromptSkillRef as aA, type TelemetrySettings as aB, type MemoryToolSchema as aa, type MemoryTurnMessage as ab, type PersonalityPreset as ac, type PluginContext as ad, type PostAssistantReplyContext as ae, type PreToolCallContext as af, type PreUserSendContext as ag, type PreUserSendResult as ah, type ProviderCapability as ai, type ProviderRoute as aj, type RecordSessionSummaryArgs as ak, type ResolvedProviderRoute as al, type RunUntilIterator as am, type SDKAgentPlugins as an, type SDKAgentSkillDetail as ao, type SDKAgentSkills as ap, type SDKArtifact as aq, type SDKContextManager as ar, type SDKPluginMetadata as as, type SDKProvidersManager as at, type SettingSource as au, Skill as av, type SkillsResolver as aw, type SkillsResolverContext as ax, type SystemPromptContext as ay, type SystemPromptMemoryFact as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, Plugin as m, type MemoryProvider as n, type MemoryId as o, type PreToolCallDecision as p, type StepResult as q, type SDKProvider as r, type ActiveMemoryPassArgs as s, type ActiveMemoryPassResult as t, type AgentMemory as u, type BudgetCheck as v, type BudgetTotal as w, type BudgetUsageEvent as x, type CloudEnv as y, type CloudRepo as z };
+export { type GoalOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type ContextBudget as D, type ContextManagerKind as E, type ContextSnapshot as F, type GetAgentOptions as G, type ContextSource as H, type InlineSkill as I, type ContextSourceStatus as J, type CreateSkillSpec as K, type LocalOptions as L, type MemorySettings as M, Cron as N, type CronCreateOptions as O, type ProviderRoutingSettings as P, type CronGetOptions as Q, type CronJob as R, type SystemPromptResolver as S, type CronJobStatus as T, type CronListOptions as U, type CronOperationOptions as V, type CronRunOptions as W, type CronRuntime as X, type CronSchedulerStatus as Y, type CronStartOptions as Z, type GoalEvent as _, type AgentDefinition as a, type GoalResult as a0, type HookName as a1, type InvalidateCacheOptions as a2, type MemoryAdapter as a3, type MemoryAdapterCapabilities as a4, type MemoryContext as a5, type MemoryFact as a6, type MemoryProviderHandle as a7, type MemoryProviderInitOptions as a8, type MemoryRevision as a9, type SystemPromptContext as aA, type SystemPromptMemoryFact as aB, type SystemPromptSkillRef as aC, type TelemetrySettings as aD, type MemoryToolSchema as aa, type MemoryTurnMessage as ab, type PersonalityPreset as ac, type PluginContext as ad, type PostAssistantReplyContext as ae, type PreToolCallContext as af, type PreUserSendContext as ag, type PreUserSendResult as ah, type ProviderCapability as ai, type ProviderRoute as aj, type RecordSessionSummaryArgs as ak, type ResolvedProviderRoute as al, type RunUntilIterator as am, type SDKAgentPlugins as an, type SDKAgentSkillDetail as ao, type SDKAgentSkills as ap, type SDKArtifact as aq, type SDKContextManager as ar, type SDKPluginMetadata as as, type SDKProvidersManager as at, type SessionRecord as au, type SessionStore as av, type SettingSource as aw, Skill as ax, type SkillsResolver as ay, type SkillsResolverContext as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, Plugin as m, type MemoryProvider as n, type MemoryId as o, type PreToolCallDecision as p, type StepResult as q, type SDKProvider as r, type ActiveMemoryPassArgs as s, type ActiveMemoryPassResult as t, type AgentMemory as u, type BudgetCheck as v, type BudgetTotal as w, type BudgetUsageEvent as x, type CloudEnv as y, type CloudRepo as z };

package/dist/{cron-BfPhZjRJ.d.cts → cron-BlAjYOew.d.cts}

@@ -626,6 +626,84 @@ declare class Skill {
     static create(spec: CreateSkillSpec): InlineSkill;
 }
 
+/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
+interface SessionRecord {
+    type: "user" | "assistant" | "system";
+    uuid: string;
+    parentUuid: string | null;
+    sessionId: string;
+    timestamp: string;
+    isSidechain?: boolean;
+    userType?: string;
+    cwd?: string;
+    version?: string;
+    subtype?: string;
+    compactMetadata?: {
+        preTokens: number;
+        trigger: string;
+    };
+    message?: Record<string, unknown>;
+}
+
+/**
+ * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
+ *
+ * A minimal, two-method port so an external store (Postgres / Redis / KV /
+ * durable object) can be the **primary store AND resume source** — the
+ * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
+ * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
+ * NOT that removed ~10-method adapter: the seam is JUST record read/append over
+ * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
+ * delete / objective methods).
+ *
+ * The SDK ships a real default implementation, `FsSessionStore`, that reads and
+ * append-writes the native Claude-shaped `.jsonl` transcript — omitting
+ * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
+ * consumer change). Injected via `local.sessionStore` for external stores.
+ *
+ * Consistency contract: `appendRecords` is append-only and ordering-preserving.
+ * The FS default serializes appends per agent with a cross-process file lock;
+ * external implementations own (and MUST document) their own concurrency
+ * guarantees for two hosts appending to the same `agentId`.
+ *
+ * @public
+ */
+
+/**
+ * The pluggable session-store seam. Exactly two methods over the native
+ * {@link SessionRecord} shape.
+ *
+ * @public
+ */
+interface SessionStore {
+    /**
+     * Return every persisted record for `agentId`, in append order. A session
+     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
+     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
+     * records via the native DAG reader, so the shape MUST be the exact
+     * {@link SessionRecord} the SDK writes.
+     *
+     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
+     * MUST throw a typed error rather than silently returning `[]` — a silent
+     * empty read would masquerade as "no history" and drop the conversation.
+     */
+    readRecords(agentId: string): Promise<SessionRecord[]>;
+    /**
+     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
+     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
+     * format is an append-only `parentUuid` DAG (compaction is a new-root
+     * `compact_boundary` record, still an append).
+     *
+     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
+     * is never blocked by store I/O — an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write). An external store that
+     * must guarantee durability should make `appendRecords` resilient (retry /
+     * durable write) internally. This differs from {@link SessionStore.readRecords},
+     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
+     */
+    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+}
+
 /**
  * Context manager backend.
  *
@@ -989,6 +1067,16 @@ interface LocalOptions {
      * Set to `~/.claude` to write sessions the Claude Code CLI can `--continue`.
      */
     baseDir?: string;
+    /**
+     * SE41 — inject an external {@link import("./session-store.js").SessionStore}
+     * (Postgres / Redis / KV / durable object) as the PRIMARY session store and
+     * resume source. Omit for the default FS transcript store (`baseDir` above) —
+     * byte-identical to SE40. Use this for serverless (ephemeral FS) or multi-host /
+     * multi-pod deployments where a resumed agent must read its history from a shared
+     * store instead of local disk. The records stay the native Claude-shaped shape,
+     * so `--continue` interop is preserved (a store may also mirror to `~/.claude`).
+     */
+    sessionStore?: SessionStore;
 }
 /**
  * Repo to clone into a cloud agent's VM.
@@ -2442,4 +2530,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type GoalOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type ContextBudget as D, type ContextManagerKind as E, type ContextSnapshot as F, type GetAgentOptions as G, type ContextSource as H, type InlineSkill as I, type ContextSourceStatus as J, type CreateSkillSpec as K, type LocalOptions as L, type MemorySettings as M, Cron as N, type CronCreateOptions as O, type ProviderRoutingSettings as P, type CronGetOptions as Q, type CronJob as R, type SystemPromptResolver as S, type CronJobStatus as T, type CronListOptions as U, type CronOperationOptions as V, type CronRunOptions as W, type CronRuntime as X, type CronSchedulerStatus as Y, type CronStartOptions as Z, type GoalEvent as _, type AgentDefinition as a, type GoalResult as a0, type HookName as a1, type InvalidateCacheOptions as a2, type MemoryAdapter as a3, type MemoryAdapterCapabilities as a4, type MemoryContext as a5, type MemoryFact as a6, type MemoryProviderHandle as a7, type MemoryProviderInitOptions as a8, type MemoryRevision as a9, type SystemPromptSkillRef as aA, type TelemetrySettings as aB, type MemoryToolSchema as aa, type MemoryTurnMessage as ab, type PersonalityPreset as ac, type PluginContext as ad, type PostAssistantReplyContext as ae, type PreToolCallContext as af, type PreUserSendContext as ag, type PreUserSendResult as ah, type ProviderCapability as ai, type ProviderRoute as aj, type RecordSessionSummaryArgs as ak, type ResolvedProviderRoute as al, type RunUntilIterator as am, type SDKAgentPlugins as an, type SDKAgentSkillDetail as ao, type SDKAgentSkills as ap, type SDKArtifact as aq, type SDKContextManager as ar, type SDKPluginMetadata as as, type SDKProvidersManager as at, type SettingSource as au, Skill as av, type SkillsResolver as aw, type SkillsResolverContext as ax, type SystemPromptContext as ay, type SystemPromptMemoryFact as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, Plugin as m, type MemoryProvider as n, type MemoryId as o, type PreToolCallDecision as p, type StepResult as q, type SDKProvider as r, type ActiveMemoryPassArgs as s, type ActiveMemoryPassResult as t, type AgentMemory as u, type BudgetCheck as v, type BudgetTotal as w, type BudgetUsageEvent as x, type CloudEnv as y, type CloudRepo as z };
+export { type GoalOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type ContextBudget as D, type ContextManagerKind as E, type ContextSnapshot as F, type GetAgentOptions as G, type ContextSource as H, type InlineSkill as I, type ContextSourceStatus as J, type CreateSkillSpec as K, type LocalOptions as L, type MemorySettings as M, Cron as N, type CronCreateOptions as O, type ProviderRoutingSettings as P, type CronGetOptions as Q, type CronJob as R, type SystemPromptResolver as S, type CronJobStatus as T, type CronListOptions as U, type CronOperationOptions as V, type CronRunOptions as W, type CronRuntime as X, type CronSchedulerStatus as Y, type CronStartOptions as Z, type GoalEvent as _, type AgentDefinition as a, type GoalResult as a0, type HookName as a1, type InvalidateCacheOptions as a2, type MemoryAdapter as a3, type MemoryAdapterCapabilities as a4, type MemoryContext as a5, type MemoryFact as a6, type MemoryProviderHandle as a7, type MemoryProviderInitOptions as a8, type MemoryRevision as a9, type SystemPromptContext as aA, type SystemPromptMemoryFact as aB, type SystemPromptSkillRef as aC, type TelemetrySettings as aD, type MemoryToolSchema as aa, type MemoryTurnMessage as ab, type PersonalityPreset as ac, type PluginContext as ad, type PostAssistantReplyContext as ae, type PreToolCallContext as af, type PreUserSendContext as ag, type PreUserSendResult as ah, type ProviderCapability as ai, type ProviderRoute as aj, type RecordSessionSummaryArgs as ak, type ResolvedProviderRoute as al, type RunUntilIterator as am, type SDKAgentPlugins as an, type SDKAgentSkillDetail as ao, type SDKAgentSkills as ap, type SDKArtifact as aq, type SDKContextManager as ar, type SDKPluginMetadata as as, type SDKProvidersManager as at, type SessionRecord as au, type SessionStore as av, type SettingSource as aw, Skill as ax, type SkillsResolver as ay, type SkillsResolverContext as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, Plugin as m, type MemoryProvider as n, type MemoryId as o, type PreToolCallDecision as p, type StepResult as q, type SDKProvider as r, type ActiveMemoryPassArgs as s, type ActiveMemoryPassResult as t, type AgentMemory as u, type BudgetCheck as v, type BudgetTotal as w, type BudgetUsageEvent as x, type CloudEnv as y, type CloudRepo as z };

package/dist/cron.cjs

@@ -3510,6 +3510,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, "-");
 }
@@ -3736,70 +3802,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) {
@@ -5131,6 +5158,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);
 }
@@ -5168,8 +5197,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) {
@@ -5186,37 +5215,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) ?? [];
@@ -5226,15 +5249,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"
         });
@@ -5257,10 +5280,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);
@@ -5295,7 +5318,7 @@ async function runPostRunLifecycle(inputs) {
     userText,
     agentId,
     workspaceCwd,
-    baseDir,
+    sessionStore,
     model,
     onRunEvent,
     hooksExecutor,
@@ -5314,7 +5337,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
@@ -17921,6 +17945,7 @@ var init_local_agent = __esm({
     init_errors();
     init_ids();
     init_cwd_mutex();
+    init_fs_session_store();
     init_session_transcript();
     init_store();
     init_manager();
@@ -17964,6 +17989,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()`
@@ -18006,6 +18037,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({
@@ -18053,7 +18085,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 */
@@ -18109,7 +18141,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,