@theokit/sdk 4.55.0 → 4.57.0

package/dist/chunk-GJ6RK75E.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/persistence/fs-session-store.ts"],"names":[],"mappings":"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","file":"chunk-GJ6RK75E.js","sourcesContent":["/**\n * SE41 — `FsSessionStore`, the DEFAULT reference implementation of the pluggable\n * {@link SessionStore} seam. It reads and append-writes the native Claude-shaped\n * `.jsonl` transcript at `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl` — the\n * exact on-disk format SE40 introduced (the file the Claude Code CLI can\n * `--continue`). Omitting `local.sessionStore` resolves to this store, so the\n * default persistence path is byte-identical to SE40 behavior.\n *\n * `readRecords` is `readTranscript(transcriptPath(...))` (a missing session →\n * `[]`, not an error — a fresh agent has no history). `appendRecords` is a TRUE\n * append: it reads the prior records, concatenates the new-turn delta, and\n * rewrites the whole line set atomically under the SE40 cross-process file lock\n * (`writeTranscript` never shrinks — the native format is an append-only\n * `parentUuid` DAG). The parent dir is created BEFORE acquiring the lock because\n * the lock's companion `<path>.lock` file needs an existing parent dir (the SE40\n * `mkdir(dirname)`-before-lock fix).\n *\n * @internal\n */\n\nimport { mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { withFileLock } from \"./file-lock.js\";\nimport { appendJsonl } from \"./jsonl.js\";\nimport { readTranscript, type SessionRecord, transcriptPath } from \"./session-transcript.js\";\nimport { acquireSessionWriter, type SessionWriterLease } from \"./session-writer.js\";\n\n/** Options identifying the on-disk transcript location for the FS default store. */\nexport interface FsSessionStoreOptions {\n  /** Transcript base dir (`~/.theokit` default, `~/.claude` for CLI interop) — already `~`-expanded. */\n  baseDir: string;\n  /** The workspace cwd whose encoded form is the transcript project dir. */\n  cwd: string;\n}\n\n/**\n * Reference-counted leases, shared per path.\n *\n * `acquireSessionWriter` is STRICT on purpose: two concurrent acquisitions of the same path, and\n * exactly one wins — \"a lease that let both through would be decorative\" (the M81 test says exactly\n * that, and it is right). That is the primitive's contract, and it does not change.\n *\n * But within ONE process it is normal to have more than one store over the same session: the golden\n * compaction tests and the concurrent-send tests do exactly that, and they record real runtime\n * behavior. Applying the raw primitive there would turn a legitimate pattern into a\n * `SessionBusyError`.\n *\n * The reconciliation belongs here, in the primitive's consumer: the process takes ONE lease per path\n * and counts how many stores use it. The last to release actually frees it. Cross-process stays\n * strict — which is the problem M81 states (\"`exec resume --last` can write into the TUI's live\n * session\").\n */\nconst sharedLeases = new Map<string, { lease: SessionWriterLease; refs: number }>();\n\nasync function acquireShared(path: string): Promise<SessionWriterLease> {\n  const existing = sharedLeases.get(path);\n  if (existing !== undefined) {\n    existing.refs++;\n    return createProxy(path);\n  }\n  const lease = await acquireSessionWriter(path);\n  sharedLeases.set(path, { lease, refs: 1 });\n  return createProxy(path);\n}\n\n/** A handle that decrements the count; the last to release frees the real lease. */\nfunction createProxy(path: string): SessionWriterLease {\n  let released = false;\n  return {\n    sessionPath: path,\n    // The proxy forwards the renewal to the ONE real lease this path shares. Renewing through any\n    // holder is correct and is the point: the record must say \"someone in this process is still\n    // writing\", and the refcount already guarantees they are all the same owner.\n    renew: (): void => {\n      if (released) return;\n      sharedLeases.get(path)?.lease.renew();\n    },\n    release: async (): Promise<void> => {\n      if (released) return;\n      released = true;\n      const entry = sharedLeases.get(path);\n      if (entry === undefined) return;\n      entry.refs--;\n      if (entry.refs > 0) return;\n      sharedLeases.delete(path);\n      await entry.lease.release();\n    },\n  };\n}\n\n/**\n * The default `SessionStore` — reads/append-writes the native `.jsonl` transcript.\n */\nexport class FsSessionStore implements SessionStore {\n  readonly #baseDir: string;\n  readonly #cwd: string;\n  /** One lease per `agentId` — a store serves more than one session over the process lifetime. */\n  readonly #leases = new Map<string, SessionWriterLease>();\n\n  constructor(options: FsSessionStoreOptions) {\n    this.#baseDir = options.baseDir;\n    this.#cwd = options.cwd;\n  }\n\n  async readRecords(agentId: string): Promise<SessionRecord[]> {\n    return readTranscript(transcriptPath(this.#baseDir, this.#cwd, agentId));\n  }\n\n  async appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void> {\n    // Empty delta → nothing to persist (avoids an unnecessary lock + rewrite).\n    if (records.length === 0) return;\n    const path = transcriptPath(this.#baseDir, this.#cwd, agentId);\n    // mkdir BEFORE the lock: withFileLock's companion `<path>.lock` needs the parent dir.\n    await mkdir(dirname(path), { recursive: true });\n\n    await withFileLock(path, async () => {\n      // M93 — appends the DELTA instead of rewriting the whole file.\n      //\n      // Before: `readTranscript` + `writeTranscript` of everything, per turn. O(n) of I/O **and** of\n      // parsing on every turn, O(n^2) per session — the consumer note in\n      // `agents/lib/session/backtrack.ts` records 1.4 MB / 3000 lines over 200 turns.\n      //\n      // Correct because the format **is already append-only**: the `parentUuid` DAG does not depend\n      // on line order, and every record carries its own parent. `appendJsonl` **already existed in\n      // the package** and had a single caller (`eval/runner.ts`) — the primitive was there, it was\n      // the store that ignored it (rung 4).\n      //\n      // `withFileLock` stays — but the earlier claim that \"it is what serializes two concurrent\n      // `appendRecords`\" was too strong, and M93's adversarial review measured it: removing it fails\n      // no test. The reason is the paragraph above — the `parentUuid` DAG does not depend on line\n      // order, so two interleaved batches reconstruct identically. The work the lock was doing\n      // (protecting a read-modify-write) disappeared along with the rewrite.\n      //\n      // What it still covers is the TOCTOU window in `needsLineBreakBefore` (read the last byte,\n      // then write): without it, two processes can both conclude \"a \\n is missing\" and produce a\n      // blank line — which the reader discards, i.e. benign. It stays as a **declared, not\n      // mechanized** defense (the discipline in `error-handling.md` § 4: enumerate the residue\n      // rather than let a missing test pass for coverage).\n      //\n      // `writeTranscript` still exists for **compaction**, the one operation that legitimately\n      // rewrites the file.\n      for (const record of records) appendJsonl(path, record);\n    });\n  }\n\n  /**\n   * Takes the session's writer lease. Throws `SessionBusyError` when another process holds it.\n   *\n   * **Explicit, and NOT inside `appendRecords`** — M95's adversarial review measured why that\n   * matters: the `SessionStore` contract states that \"an `appendRecords` rejection is logged to\n   * stderr, NOT thrown to the caller (best-effort write)\". Acquiring there made the\n   * `SessionBusyError` get **swallowed**, and the result was worse than the original problem:\n   * instead of two writers interleaving lines, the loser **lost the turn silently** — nothing on\n   * disk, a stderr warning invisible under the TUI, and no way for the caller to react.\n   *\n   * At init the error reaches someone who can act: `exec` forks to a new id, which is exactly what\n   * the error message itself prescribes. It is the difference between failing where a decision is\n   * possible and failing where only loss is.\n   */\n  async acquire(agentId: string): Promise<void> {\n    if (this.#leases.has(agentId)) return;\n    const path = transcriptPath(this.#baseDir, this.#cwd, agentId);\n    await mkdir(dirname(path), { recursive: true });\n    this.#leases.set(agentId, await acquireShared(path));\n  }\n\n  /**\n   * Releases ONE agent's lease.\n   *\n   * It exists because `dispose()` releases **every** lease the store holds, and a store injected by\n   * the consumer may serve several agents: an init that fails for agent B must not free agent A's\n   * lease, which is still live and writing.\n   */\n  async release(agentId: string): Promise<void> {\n    const lease = this.#leases.get(agentId);\n    if (lease === undefined) return;\n    this.#leases.delete(agentId);\n    await lease.release();\n  }\n\n  /**\n   * Releases every lease this store holds.\n   *\n   * Without it the `.writer.lock` outlives the process and the next open would have to wait out the\n   * heartbeat window — recoverable, but 30 s of waiting after a CLEAN shutdown would be an avoidable\n   * defect. Idempotent: calling it twice is not an error.\n   */\n  async dispose(): Promise<void> {\n    const leases = [...this.#leases.values()];\n    this.#leases.clear();\n    for (const lease of leases) await lease.release();\n  }\n}\n"]}