@theokit/sdk 4.0.2 → 4.1.0

package/dist/internal/persistence/fs-session-store.d.cts

@@ -0,0 +1,26 @@
+/**
+ * SE41 — `FsSessionStore`, the DEFAULT reference implementation of the pluggable
+ * {@link SessionStore} seam. It reads and append-writes the native Claude-shaped
+ * `.jsonl` transcript at `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl` — the
+ * exact on-disk format SE40 introduced (the file the Claude Code CLI can
+ * `--continue`). Omitting `local.sessionStore` resolves to this store, so the
+ * default persistence path is byte-identical to SE40 behavior.
+ *
+ * `readRecords` is `readTranscript(transcriptPath(...))` (a missing session →
+ * `[]`, not an error — a fresh agent has no history). `appendRecords` is a TRUE
+ * append: it reads the prior records, concatenates the new-turn delta, and
+ * rewrites the whole line set atomically under the SE40 cross-process file lock
+ * (`writeTranscript` never shrinks — the native format is an append-only
+ * `parentUuid` DAG). The parent dir is created BEFORE acquiring the lock because
+ * the lock's companion `<path>.lock` file needs an existing parent dir (the SE40
+ * `mkdir(dirname)`-before-lock fix).
+ *
+ * @internal
+ */
+/** Options identifying the on-disk transcript location for the FS default store. */
+export interface FsSessionStoreOptions {
+    /** Transcript base dir (`~/.theokit` default, `~/.claude` for CLI interop) — already `~`-expanded. */
+    baseDir: string;
+    /** The workspace cwd whose encoded form is the transcript project dir. */
+    cwd: string;
+}

package/dist/internal/persistence/fs-session-store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SE41 — `FsSessionStore`, the DEFAULT reference implementation of the pluggable
+ * {@link SessionStore} seam. It reads and append-writes the native Claude-shaped
+ * `.jsonl` transcript at `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl` — the
+ * exact on-disk format SE40 introduced (the file the Claude Code CLI can
+ * `--continue`). Omitting `local.sessionStore` resolves to this store, so the
+ * default persistence path is byte-identical to SE40 behavior.
+ *
+ * `readRecords` is `readTranscript(transcriptPath(...))` (a missing session →
+ * `[]`, not an error — a fresh agent has no history). `appendRecords` is a TRUE
+ * append: it reads the prior records, concatenates the new-turn delta, and
+ * rewrites the whole line set atomically under the SE40 cross-process file lock
+ * (`writeTranscript` never shrinks — the native format is an append-only
+ * `parentUuid` DAG). The parent dir is created BEFORE acquiring the lock because
+ * the lock's companion `<path>.lock` file needs an existing parent dir (the SE40
+ * `mkdir(dirname)`-before-lock fix).
+ *
+ * @internal
+ */
+/** Options identifying the on-disk transcript location for the FS default store. */
+export interface FsSessionStoreOptions {
+    /** Transcript base dir (`~/.theokit` default, `~/.claude` for CLI interop) — already `~`-expanded. */
+    baseDir: string;
+    /** The workspace cwd whose encoded form is the transcript project dir. */
+    cwd: string;
+}

package/dist/internal/runtime/session/agent-session-store.d.ts

@@ -11,37 +11,45 @@
  *
  * @internal
  */
-import type { ConversationTurn } from "../../../types/conversation.js";
+import type { SessionStore } from "../../../types/session-store.js";
 import type { SessionMessage } from "./session-types.js";
 /** The turn to persist: the user's text plus the rich per-turn conversation view. */
 export interface PersistTurnInput {
     userText: string;
     conversation: readonly ConversationTurn[];
 }
-/** Options identifying the on-disk transcript for one agent. */
+/**
+ * The per-agent transcript metadata used to seed a {@link SessionTranscript}. The
+ * actual record I/O goes through the injected {@link SessionStore} (SE41), so this
+ * no longer carries a `baseDir` — the store is already bound to its location.
+ */
 export interface TranscriptLocation {
-    baseDir: string;
     cwd: string;
     agentId: string;
     model: string;
 }
 /**
- * Read the persisted transcript and reconstruct the resumable session history,
- * narrowed to the in-memory {@link SessionMessage} shape (user/assistant text).
- * Tool turns fold into assistant-role context so resume keeps tool history.
+ * Read the session's records via the {@link SessionStore} and reconstruct the
+ * resumable history, narrowed to the in-memory {@link SessionMessage} shape
+ * (user/assistant text). Tool turns fold into assistant-role context so resume
+ * keeps tool history. Works identically for the FS default and an external store.
  */
-export declare function readSessionMessages(baseDir: string, cwd: string, agentId: string): Promise<SessionMessage[]>;
+export declare function readSessionMessages(store: SessionStore, agentId: string): Promise<SessionMessage[]>;
 /**
- * Persist one conversation turn (user + assistant/tool records) to the native
- * transcript, append-only. Seeds the parent chain from the on-disk records under
- * a cross-process file lock so concurrent processes never tear the DAG.
+ * Persist one conversation turn (user + assistant/tool records) to the session
+ * store, append-only. Reads the prior records to seed the parent chain, folds the
+ * new turn, and appends ONLY the delta via {@link SessionStore.appendRecords}
+ * (the store owns the append atomicity — the FS default serializes under a file
+ * lock). Within one process, turns for an agent are already chained upstream, so
+ * the read→append is ordered; cross-host ordering is the external store's contract.
  */
-export declare function persistTurn(loc: TranscriptLocation, sessionId: string, turn: PersistTurnInput): Promise<void>;
+export declare function persistTurn(store: SessionStore, loc: TranscriptLocation, sessionId: string, turn: PersistTurnInput): Promise<void>;
 /**
  * Append-only compaction: add a `compact_boundary` system record (a new root) so
- * resume replays only the post-boundary continuation. NEVER shrinks the line set.
+ * resume replays only the post-boundary continuation. Appends only the boundary
+ * record via the store — NEVER rewrites or shrinks the prior records.
  */
-export declare function appendCompactBoundaryRecord(loc: TranscriptLocation, sessionId: string, meta: {
+export declare function appendCompactBoundaryRecord(store: SessionStore, loc: TranscriptLocation, sessionId: string, meta: {
     preTokens: number;
     trigger: string;
 }): Promise<void>;

package/dist/types/agent.d.ts

@@ -28,6 +28,16 @@ export 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?: import("./session-store.js").SessionStore;
 }
 /**
  * Repo to clone into a cloud agent's VM.

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ export type * from "./messages.js";
 export type * from "./processors.js";
 export type * from "./providers.js";
 export type * from "./run.js";
+export type * from "./session-store.js";
 export type * from "./task.js";
 export type * from "./theokit.js";
 export type * from "./trajectory.js";

package/dist/types/session-store.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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
+ */
+import type { SessionRecord } from "../internal/persistence/session-transcript.js";
+export type { SessionRecord } from "../internal/persistence/session-transcript.js";
+/**
+ * The pluggable session-store seam. Exactly two methods over the native
+ * {@link SessionRecord} shape.
+ *
+ * @public
+ */
+export 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>;
+}

package/package.json

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