@open-gitagent/session-store-mongo 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ComputerAgent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @computeragent/session-store-mongo
+
+MongoDB-backed `SessionStore` for the ComputerAgent harness. Plug-in implementation of the Claude Agent SDK's native `SessionStore` contract — enables cross-process conversation continuation when sessions live in a shared database instead of on local disk.
+
+## Install
+
+```bash
+pnpm add @computeragent/session-store-mongo
+```
+
+## Use
+
+Register the store with the harness server at boot:
+
+```ts
+import { createHarnessServer } from "@computeragent/harness-server";
+import { MongoSessionStore } from "@computeragent/session-store-mongo";
+
+const app = createHarnessServer({
+  engines: { /* ... */ },
+  identityLoaders: { /* ... */ },
+  sessionStores: {
+    mongo: (options) => new MongoSessionStore({
+      url: process.env.MONGO_URL!,
+      database: "computeragent_sessions",
+      ...(options as object ?? {}),
+    }),
+  },
+});
+```
+
+Then have any client request the store by `kind`:
+
+```ts
+const agent = new ComputerAgent({
+  source: "...",
+  harness: "claude-agent-sdk",
+  sessionStore: { kind: "mongo" },
+  sessionId: previousSessionId,  // for resume
+  envs: { ANTHROPIC_API_KEY: "..." },
+});
+```
+
+The server-side builder receives the wire-side `options` field; the SDK never carries connection credentials over the wire — keep them server-side.
+
+## Storage layout
+
+One document per session under the `sessions` collection of the configured database (default: `computeragent_sessions`):
+
+```json
+{
+  "_id": "<sessionId>",
+  "projectKey": "<engine-derived>",
+  "entries": [ /* SessionStoreEntry */ ],
+  "updatedAt": <Date>
+}
+```
+
+`entries[]` follows the Claude Agent SDK's [`SessionStoreEntry`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) shape — JSONL-equivalent records the SDK appends per turn (user messages, assistant responses, tool calls, system events).
+
+## Architecture notes
+
+- **Two engines, one port.** The `SessionStore` interface is engine-agnostic. The Claude Agent engine consumes it natively (the SDK reads/writes through it). The gitagent engine currently manages its own filesystem session format and ignores `ctx.sessionStore`; a future `GitclawSessionStoreAdapter` can mirror gitclaw's session dir into any `SessionStore` for symmetric resume across engines.
+- **Idempotency.** Entries are deduplicated by `uuid`. Re-appends of an entry already present are no-ops — safe for SDK retries and `importSessionToStore` replays.
+- **Single-writer.** A simple `load → filter → write` cycle. Concurrent writes against the same `sessionId` from different harness processes can interleave; the SDK's flow is single-writer per session, which makes this correct in practice. Multi-writer parallelism (e.g., a fan-out farm against one logical session) would require a transactional update pipeline — captured as future work.
+
+## Configuration
+
+```ts
+new MongoSessionStore({
+  url: "mongodb://user:pass@host:port/admin",  // required
+  database: "computeragent_sessions",          // default
+  collection: "sessions",                      // default
+  clientOptions: { /* MongoClientOptions */ }, // optional, forwarded to driver
+});
+```
+
+`close()` releases the underlying `MongoClient` cleanly. The store auto-connects on first `append`/`load`/`size`/`listSessions` call; explicit `connect()` is offered for callers that want to surface connection errors at boot.
+
+## Tests
+
+```bash
+MONGO_URL="mongodb://..." pnpm --filter @computeragent/session-store-mongo test
+```
+
+Live integration tests use ephemeral `ca_test_<random>` databases that are dropped on teardown — safe to run against shared clusters without polluting other apps' data. With `MONGO_URL` unset the live suite is skipped automatically.

package/dist/builder.d.ts

@@ -0,0 +1,22 @@
+import type { SessionStore } from "@open-gitagent/protocol";
+import { type MongoSessionStoreOptions } from "./mongo-store.js";
+/**
+ * One-call builder for the harness server's `sessionStores` registry.
+ * Wraps `MongoSessionStore` so users can register the Mongo backend in a
+ * single line:
+ *
+ *   createHarnessServer({
+ *     ...,
+ *     sessionStores: { mongo: mongoSessionStoreBuilder({ url: process.env.MONGO_URL! }) },
+ *   });
+ *
+ * The returned builder honors per-call `options` from the wire-side
+ * `SessionStoreConfig.options` — useful when different sessions need
+ * different databases or collections under the same Mongo cluster:
+ *
+ *   client side:  sessionStore: { kind: "mongo", options: { database: "tenant_a" } }
+ *
+ * Per-call options merge on top of the defaults passed to this helper.
+ */
+export declare function mongoSessionStoreBuilder(defaults: MongoSessionStoreOptions): (options?: unknown) => SessionStore;
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAqB,KAAK,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEpF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,wBAAwB,GACjC,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,YAAY,CAMrC"}

package/dist/builder.js

@@ -0,0 +1,28 @@
+import { MongoSessionStore } from "./mongo-store.js";
+/**
+ * One-call builder for the harness server's `sessionStores` registry.
+ * Wraps `MongoSessionStore` so users can register the Mongo backend in a
+ * single line:
+ *
+ *   createHarnessServer({
+ *     ...,
+ *     sessionStores: { mongo: mongoSessionStoreBuilder({ url: process.env.MONGO_URL! }) },
+ *   });
+ *
+ * The returned builder honors per-call `options` from the wire-side
+ * `SessionStoreConfig.options` — useful when different sessions need
+ * different databases or collections under the same Mongo cluster:
+ *
+ *   client side:  sessionStore: { kind: "mongo", options: { database: "tenant_a" } }
+ *
+ * Per-call options merge on top of the defaults passed to this helper.
+ */
+export function mongoSessionStoreBuilder(defaults) {
+    if (!defaults.url)
+        throw new Error("mongoSessionStoreBuilder: defaults.url is required");
+    return (options) => {
+        const overrides = (options ?? {});
+        return new MongoSessionStore({ ...defaults, ...overrides });
+    };
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAiC,MAAM,kBAAkB,CAAC;AAEpF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAkC;IAElC,IAAI,CAAC,QAAQ,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACzF,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,SAAS,GAAG,CAAC,OAAO,IAAI,EAAE,CAAsC,CAAC;QACvE,OAAO,IAAI,iBAAiB,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;IAC9D,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { MongoSessionStore } from "./mongo-store.js";
+export type { MongoSessionStoreOptions } from "./mongo-store.js";
+export { mongoSessionStoreBuilder } from "./builder.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { MongoSessionStore } from "./mongo-store.js";
+export { mongoSessionStoreBuilder } from "./builder.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/mongo-store.d.ts

@@ -0,0 +1,56 @@
+import { type MongoClientOptions } from "mongodb";
+import type { SessionKey, SessionStore, SessionStoreEntry } from "@open-gitagent/protocol";
+/**
+ * MongoDB-backed SessionStore. One document per session, keyed by sessionId.
+ *
+ * Document shape:
+ *   {
+ *     _id: <sessionId>,
+ *     projectKey: <string>,
+ *     entries: [<SessionStoreEntry>, ...],
+ *     updatedAt: <Date>,
+ *   }
+ *
+ * Idempotency by entry.uuid: a duplicate uuid append is skipped. Currently
+ * implemented with a load-then-write pattern, which is correct for single-
+ * writer flows (the harness server is single-writer per session). Multi-
+ * writer correctness requires either an aggregation-pipeline update or a
+ * lock; documented limitation.
+ *
+ * Lifecycle: pass a `mongoUrl` to construct, call `connect()` once before
+ * first use (lazy: `append`/`load` will auto-connect on first call), and
+ * `close()` when done.
+ */
+export interface MongoSessionStoreOptions {
+    /** Mongo connection string. Required. */
+    readonly url: string;
+    /** Database name. Default: `computeragent_sessions`. */
+    readonly database?: string;
+    /** Collection name. Default: `sessions`. */
+    readonly collection?: string;
+    /** Optional MongoClient options forwarded verbatim. */
+    readonly clientOptions?: MongoClientOptions;
+}
+export declare class MongoSessionStore implements SessionStore {
+    private readonly client;
+    private readonly databaseName;
+    private readonly collectionName;
+    private connected;
+    private connectPromise;
+    constructor(opts: MongoSessionStoreOptions);
+    /** Open the connection. Idempotent; lazy callers don't need to invoke this. */
+    connect(): Promise<void>;
+    /** Close the MongoClient. Safe to call multiple times. */
+    close(): Promise<void>;
+    append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
+    load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
+    /** Test/admin helper: number of entries stored for a sessionId. */
+    size(sessionId: string): Promise<number>;
+    /** Diagnostic: list the most-recently-touched sessions. */
+    listSessions(projectKey: string): Promise<{
+        sessionId: string;
+        mtime: number;
+    }[]>;
+    private collection;
+}
+//# sourceMappingURL=mongo-store.d.ts.map

package/dist/mongo-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-store.d.ts","sourceRoot":"","sources":["../src/mongo-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyC,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAC;CAC7C;AASD,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAA8B;gBAExC,IAAI,EAAE,wBAAwB;IAO1C,+EAA+E;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,0DAA0D;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBpE,IAAI,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,EAAE,GAAG,IAAI,CAAC;IAOhE,mEAAmE;IAC7D,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM9C,2DAA2D;IACrD,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;YAUzE,UAAU;CAKzB"}

package/dist/mongo-store.js

@@ -0,0 +1,79 @@
+import { MongoClient } from "mongodb";
+export class MongoSessionStore {
+    client;
+    databaseName;
+    collectionName;
+    connected = false;
+    connectPromise = null;
+    constructor(opts) {
+        if (!opts.url)
+            throw new Error("MongoSessionStore: url is required");
+        this.client = new MongoClient(opts.url, opts.clientOptions);
+        this.databaseName = opts.database ?? "computeragent_sessions";
+        this.collectionName = opts.collection ?? "sessions";
+    }
+    /** Open the connection. Idempotent; lazy callers don't need to invoke this. */
+    async connect() {
+        if (this.connected)
+            return;
+        if (!this.connectPromise) {
+            this.connectPromise = this.client.connect().then(() => {
+                this.connected = true;
+            });
+        }
+        await this.connectPromise;
+    }
+    /** Close the MongoClient. Safe to call multiple times. */
+    async close() {
+        if (!this.connected)
+            return;
+        this.connected = false;
+        this.connectPromise = null;
+        await this.client.close();
+    }
+    async append(key, entries) {
+        if (entries.length === 0)
+            return;
+        const coll = await this.collection();
+        const doc = await coll.findOne({ _id: key.sessionId });
+        const existing = doc?.entries ?? [];
+        const seenUuids = new Set(existing.map((e) => e.uuid).filter((u) => typeof u === "string"));
+        const fresh = entries.filter((e) => !e.uuid || !seenUuids.has(e.uuid));
+        if (fresh.length === 0)
+            return;
+        await coll.updateOne({ _id: key.sessionId }, {
+            $push: { entries: { $each: fresh } },
+            $set: { projectKey: key.projectKey, updatedAt: new Date() },
+            $setOnInsert: { _id: key.sessionId },
+        }, { upsert: true });
+    }
+    async load(key) {
+        const coll = await this.collection();
+        const doc = await coll.findOne({ _id: key.sessionId });
+        if (!doc?.entries || doc.entries.length === 0)
+            return null;
+        return doc.entries;
+    }
+    /** Test/admin helper: number of entries stored for a sessionId. */
+    async size(sessionId) {
+        const coll = await this.collection();
+        const doc = await coll.findOne({ _id: sessionId });
+        return doc?.entries?.length ?? 0;
+    }
+    /** Diagnostic: list the most-recently-touched sessions. */
+    async listSessions(projectKey) {
+        const coll = await this.collection();
+        const docs = await coll
+            .find({ projectKey })
+            .sort({ updatedAt: -1 })
+            .limit(50)
+            .toArray();
+        return docs.map((d) => ({ sessionId: d._id, mtime: d.updatedAt.getTime() }));
+    }
+    async collection() {
+        await this.connect();
+        const db = this.client.db(this.databaseName);
+        return db.collection(this.collectionName);
+    }
+}
+//# sourceMappingURL=mongo-store.js.map

package/dist/mongo-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-store.js","sourceRoot":"","sources":["../src/mongo-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAqD,MAAM,SAAS,CAAC;AA8CzF,MAAM,OAAO,iBAAiB;IACX,MAAM,CAAc;IACpB,YAAY,CAAS;IACrB,cAAc,CAAS;IAChC,SAAS,GAAG,KAAK,CAAC;IAClB,cAAc,GAAyB,IAAI,CAAC;IAEpD,YAAY,IAA8B;QACxC,IAAI,CAAC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACrE,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAC5D,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,QAAQ,IAAI,wBAAwB,CAAC;QAC9D,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC;IACtD,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;gBACpD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACxB,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,CAAC,cAAc,CAAC;IAC5B,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAe,EAAE,OAA4B;QACxD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACjC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,GAAG,CACvB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAC9E,CAAC;QACF,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACvE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,MAAM,IAAI,CAAC,SAAS,CAClB,EAAE,GAAG,EAAE,GAAG,CAAC,SAAS,EAAE,EACtB;YACE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAW,EAAE;YAC7C,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE;YAC3D,YAAY,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,SAAS,EAAW;SAC9C,EACD,EAAE,MAAM,EAAE,IAAI,EAAE,CACjB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAe;QACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,GAAG,EAAE,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3D,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,IAAI,CAAC,SAAiB;QAC1B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;QACnD,OAAO,GAAG,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,YAAY,CAAC,UAAkB;QACnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,IAAI;aACpB,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;aACpB,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC;aACvB,KAAK,CAAC,EAAE,CAAC;aACT,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC/E,CAAC;IAEO,KAAK,CAAC,UAAU;QACtB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,EAAE,GAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACjD,OAAO,EAAE,CAAC,UAAU,CAAa,IAAI,CAAC,cAAc,CAAC,CAAC;IACxD,CAAC;CACF"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@open-gitagent/session-store-mongo",
+  "version": "0.2.1",
+  "description": "MongoDB-backed SessionStore for the ComputerAgent harness — plug-in implementation of the Claude Agent SDK's SessionStore contract.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "mongodb": "^6.10.0",
+    "@open-gitagent/protocol": "0.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "ai-agents",
+    "session-store",
+    "mongodb",
+    "memory",
+    "computeragent"
+  ],
+  "homepage": "https://github.com/open-gitagent/ComputerAgent",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-gitagent/ComputerAgent.git",
+    "directory": "packages/session-store-mongo"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
+}

package/src/builder.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { mongoSessionStoreBuilder } from "./builder.js";
+
+describe("mongoSessionStoreBuilder", () => {
+  it("returns a builder that constructs a MongoSessionStore from defaults", () => {
+    const build = mongoSessionStoreBuilder({
+      url: "mongodb://localhost:27017/admin",
+      database: "default_db",
+    });
+    const store = build();
+    // Constructed without throwing — connection is lazy.
+    expect(store).toBeDefined();
+    // Cleanup so we don't leak the MongoClient.
+    void (store as { close?: () => Promise<void> }).close?.();
+  });
+
+  it("merges per-call options on top of defaults", () => {
+    const build = mongoSessionStoreBuilder({
+      url: "mongodb://localhost:27017/admin",
+      database: "default_db",
+    });
+    // No assertion on internal shape (private fields), but the call should not throw
+    // and should produce an instance — that's the contract we expose.
+    const store = build({ database: "override_db" });
+    expect(store).toBeDefined();
+    void (store as { close?: () => Promise<void> }).close?.();
+  });
+
+  it("throws if defaults.url is empty", () => {
+    expect(() => mongoSessionStoreBuilder({ url: "" })).toThrow();
+  });
+});

package/src/builder.ts

@@ -0,0 +1,30 @@
+import type { SessionStore } from "@open-gitagent/protocol";
+import { MongoSessionStore, type MongoSessionStoreOptions } from "./mongo-store.js";
+
+/**
+ * One-call builder for the harness server's `sessionStores` registry.
+ * Wraps `MongoSessionStore` so users can register the Mongo backend in a
+ * single line:
+ *
+ *   createHarnessServer({
+ *     ...,
+ *     sessionStores: { mongo: mongoSessionStoreBuilder({ url: process.env.MONGO_URL! }) },
+ *   });
+ *
+ * The returned builder honors per-call `options` from the wire-side
+ * `SessionStoreConfig.options` — useful when different sessions need
+ * different databases or collections under the same Mongo cluster:
+ *
+ *   client side:  sessionStore: { kind: "mongo", options: { database: "tenant_a" } }
+ *
+ * Per-call options merge on top of the defaults passed to this helper.
+ */
+export function mongoSessionStoreBuilder(
+  defaults: MongoSessionStoreOptions,
+): (options?: unknown) => SessionStore {
+  if (!defaults.url) throw new Error("mongoSessionStoreBuilder: defaults.url is required");
+  return (options) => {
+    const overrides = (options ?? {}) as Partial<MongoSessionStoreOptions>;
+    return new MongoSessionStore({ ...defaults, ...overrides });
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { MongoSessionStore } from "./mongo-store.js";
+export type { MongoSessionStoreOptions } from "./mongo-store.js";
+export { mongoSessionStoreBuilder } from "./builder.js";

package/src/mongo-store.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it, beforeAll, afterAll, beforeEach } from "vitest";
+import { MongoClient } from "mongodb";
+import { MongoSessionStore } from "./mongo-store.js";
+
+/**
+ * Integration tests against a live MongoDB. Skipped automatically when
+ * `MONGO_URL` is not set in the environment — keeps CI green for forks
+ * without a Mongo cluster while still being load-bearing when run with
+ * credentials.
+ *
+ * Each test uses a unique database name (`ca_test_<random>`) and drops
+ * it on teardown so concurrent runs don't collide.
+ */
+const url = process.env.MONGO_URL;
+const describeMongo = url ? describe : describe.skip;
+
+describeMongo("MongoSessionStore (live)", () => {
+  let cleanupClient: MongoClient | null = null;
+  let dbName: string;
+  let store: MongoSessionStore;
+
+  beforeAll(async () => {
+    cleanupClient = new MongoClient(url!);
+    await cleanupClient.connect();
+  });
+
+  afterAll(async () => {
+    if (cleanupClient) await cleanupClient.close();
+  });
+
+  beforeEach(async () => {
+    dbName = `ca_test_${Math.random().toString(36).slice(2, 10)}`;
+    store = new MongoSessionStore({ url: url!, database: dbName });
+  });
+
+  const cleanup = async () => {
+    try { await cleanupClient?.db(dbName).dropDatabase(); } catch { /* ignore */ }
+    await store.close();
+  };
+
+  it("load() on a never-written key returns null", async () => {
+    try {
+      const r = await store.load({ projectKey: "p", sessionId: "nope" });
+      expect(r).toBeNull();
+    } finally { await cleanup(); }
+  });
+
+  it("append then load round-trips entries", async () => {
+    try {
+      const key = { projectKey: "p", sessionId: "s1" };
+      await store.append(key, [
+        { type: "user", uuid: "a", text: "hi" },
+        { type: "assistant", uuid: "b", text: "hello" },
+      ]);
+      const loaded = await store.load(key);
+      expect(loaded).toHaveLength(2);
+      expect((loaded![0] as { uuid: string }).uuid).toBe("a");
+    } finally { await cleanup(); }
+  });
+
+  it("appends accumulate across calls", async () => {
+    try {
+      const key = { projectKey: "p", sessionId: "s1" };
+      await store.append(key, [{ type: "u", uuid: "a" }]);
+      await store.append(key, [{ type: "u", uuid: "b" }]);
+      expect(await store.size("s1")).toBe(2);
+    } finally { await cleanup(); }
+  });
+
+  it("idempotent by entry.uuid", async () => {
+    try {
+      const key = { projectKey: "p", sessionId: "s1" };
+      await store.append(key, [{ type: "u", uuid: "a" }]);
+      await store.append(key, [{ type: "u", uuid: "a" }]);
+      expect(await store.size("s1")).toBe(1);
+    } finally { await cleanup(); }
+  });
+
+  it("survives across two MongoSessionStore instances (the resume scenario)", async () => {
+    try {
+      const a = store;
+      const key = { projectKey: "p", sessionId: "s1" };
+      await a.append(key, [{ type: "u", uuid: "a", text: "remember 47" }]);
+      const b = new MongoSessionStore({ url: url!, database: dbName });
+      const loaded = await b.load(key);
+      expect(loaded).toEqual([{ type: "u", uuid: "a", text: "remember 47" }]);
+      await b.close();
+    } finally { await cleanup(); }
+  });
+
+  it("different sessionIds isolated under the same database", async () => {
+    try {
+      await store.append({ projectKey: "p", sessionId: "alpha" }, [{ type: "u", uuid: "1" }]);
+      await store.append({ projectKey: "p", sessionId: "beta" }, [{ type: "u", uuid: "2" }]);
+      expect(await store.size("alpha")).toBe(1);
+      expect(await store.size("beta")).toBe(1);
+    } finally { await cleanup(); }
+  });
+
+  it("listSessions returns recently-written sessions for a projectKey", async () => {
+    try {
+      await store.append({ projectKey: "demo", sessionId: "x" }, [{ type: "u" }]);
+      await store.append({ projectKey: "demo", sessionId: "y" }, [{ type: "u" }]);
+      const sessions = await store.listSessions("demo");
+      expect(sessions.length).toBeGreaterThanOrEqual(2);
+    } finally { await cleanup(); }
+  });
+});
+
+describe("MongoSessionStore (offline contract)", () => {
+  it("constructor rejects empty url", () => {
+    expect(() => new MongoSessionStore({ url: "" })).toThrow();
+  });
+});

package/src/mongo-store.ts

@@ -0,0 +1,131 @@
+import { MongoClient, type Collection, type Db, type MongoClientOptions } from "mongodb";
+import type {
+  SessionKey,
+  SessionStore,
+  SessionStoreEntry,
+} from "@open-gitagent/protocol";
+
+/**
+ * MongoDB-backed SessionStore. One document per session, keyed by sessionId.
+ *
+ * Document shape:
+ *   {
+ *     _id: <sessionId>,
+ *     projectKey: <string>,
+ *     entries: [<SessionStoreEntry>, ...],
+ *     updatedAt: <Date>,
+ *   }
+ *
+ * Idempotency by entry.uuid: a duplicate uuid append is skipped. Currently
+ * implemented with a load-then-write pattern, which is correct for single-
+ * writer flows (the harness server is single-writer per session). Multi-
+ * writer correctness requires either an aggregation-pipeline update or a
+ * lock; documented limitation.
+ *
+ * Lifecycle: pass a `mongoUrl` to construct, call `connect()` once before
+ * first use (lazy: `append`/`load` will auto-connect on first call), and
+ * `close()` when done.
+ */
+export interface MongoSessionStoreOptions {
+  /** Mongo connection string. Required. */
+  readonly url: string;
+  /** Database name. Default: `computeragent_sessions`. */
+  readonly database?: string;
+  /** Collection name. Default: `sessions`. */
+  readonly collection?: string;
+  /** Optional MongoClient options forwarded verbatim. */
+  readonly clientOptions?: MongoClientOptions;
+}
+
+interface SessionDoc {
+  _id: string;
+  projectKey: string;
+  entries: SessionStoreEntry[];
+  updatedAt: Date;
+}
+
+export class MongoSessionStore implements SessionStore {
+  private readonly client: MongoClient;
+  private readonly databaseName: string;
+  private readonly collectionName: string;
+  private connected = false;
+  private connectPromise: Promise<void> | null = null;
+
+  constructor(opts: MongoSessionStoreOptions) {
+    if (!opts.url) throw new Error("MongoSessionStore: url is required");
+    this.client = new MongoClient(opts.url, opts.clientOptions);
+    this.databaseName = opts.database ?? "computeragent_sessions";
+    this.collectionName = opts.collection ?? "sessions";
+  }
+
+  /** Open the connection. Idempotent; lazy callers don't need to invoke this. */
+  async connect(): Promise<void> {
+    if (this.connected) return;
+    if (!this.connectPromise) {
+      this.connectPromise = this.client.connect().then(() => {
+        this.connected = true;
+      });
+    }
+    await this.connectPromise;
+  }
+
+  /** Close the MongoClient. Safe to call multiple times. */
+  async close(): Promise<void> {
+    if (!this.connected) return;
+    this.connected = false;
+    this.connectPromise = null;
+    await this.client.close();
+  }
+
+  async append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void> {
+    if (entries.length === 0) return;
+    const coll = await this.collection();
+    const doc = await coll.findOne({ _id: key.sessionId });
+    const existing = doc?.entries ?? [];
+    const seenUuids = new Set(
+      existing.map((e) => e.uuid).filter((u): u is string => typeof u === "string"),
+    );
+    const fresh = entries.filter((e) => !e.uuid || !seenUuids.has(e.uuid));
+    if (fresh.length === 0) return;
+    await coll.updateOne(
+      { _id: key.sessionId },
+      {
+        $push: { entries: { $each: fresh } as never },
+        $set: { projectKey: key.projectKey, updatedAt: new Date() },
+        $setOnInsert: { _id: key.sessionId } as never,
+      },
+      { upsert: true },
+    );
+  }
+
+  async load(key: SessionKey): Promise<SessionStoreEntry[] | null> {
+    const coll = await this.collection();
+    const doc = await coll.findOne({ _id: key.sessionId });
+    if (!doc?.entries || doc.entries.length === 0) return null;
+    return doc.entries;
+  }
+
+  /** Test/admin helper: number of entries stored for a sessionId. */
+  async size(sessionId: string): Promise<number> {
+    const coll = await this.collection();
+    const doc = await coll.findOne({ _id: sessionId });
+    return doc?.entries?.length ?? 0;
+  }
+
+  /** Diagnostic: list the most-recently-touched sessions. */
+  async listSessions(projectKey: string): Promise<{ sessionId: string; mtime: number }[]> {
+    const coll = await this.collection();
+    const docs = await coll
+      .find({ projectKey })
+      .sort({ updatedAt: -1 })
+      .limit(50)
+      .toArray();
+    return docs.map((d) => ({ sessionId: d._id, mtime: d.updatedAt.getTime() }));
+  }
+
+  private async collection(): Promise<Collection<SessionDoc>> {
+    await this.connect();
+    const db: Db = this.client.db(this.databaseName);
+    return db.collection<SessionDoc>(this.collectionName);
+  }
+}