cimux-mcp 0.1.0

package/dist/storage/sqlite-cimux-store.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { createContextPackagePreview, contextPackageSchema, mailboxNameSchema, mailboxSchema, normalizeInboxPreviewLimit } from "../model/context-package.js";
+export class SQLiteCimuxStore {
+    db;
+    constructor(databasePath) {
+        // The caller decides where the local Cimux database lives. Production code
+        // will point this at ~/.cimux/inbox.sqlite; tests can use a temp path.
+        fs.mkdirSync(path.dirname(databasePath), { recursive: true });
+        this.db = new DatabaseSync(databasePath);
+        this.db.exec("pragma foreign_keys = ON;");
+        this.migrate();
+    }
+    async createMailbox(name) {
+        const parsedName = mailboxNameSchema.parse(name);
+        const now = new Date().toISOString();
+        // Creating a mailbox is idempotent so repeated session registration can
+        // safely call this without resetting the durable mailbox record.
+        this.db
+            .prepare(`insert into mailboxes (name, created_at, last_seen_at)
+         values (?, ?, null)
+         on conflict(name) do nothing`)
+            .run(parsedName, now);
+        const mailbox = await this.getMailbox(parsedName);
+        if (!mailbox) {
+            throw new Error(`Mailbox was not created: ${parsedName}`);
+        }
+        return mailbox;
+    }
+    async getMailbox(name) {
+        const parsedName = mailboxNameSchema.parse(name);
+        const row = this.db
+            .prepare("select name, created_at, last_seen_at from mailboxes where name = ?")
+            .get(parsedName);
+        return row ? toMailbox(row) : null;
+    }
+    async listMailboxes() {
+        const rows = this.db
+            .prepare("select name, created_at, last_seen_at from mailboxes order by name asc")
+            .all();
+        return rows.map(toMailbox);
+    }
+    async createContextPackage(contextPackage) {
+        const parsed = contextPackageSchema.parse(contextPackage);
+        await this.assertMailboxExists(parsed.fromMailbox);
+        await this.assertMailboxExists(parsed.toMailbox);
+        this.db
+            .prepare(`insert into context_packages (
+          id,
+          from_mailbox,
+          to_mailbox,
+          title,
+          summary,
+          body,
+          tags_json,
+          artifacts_json,
+          payload_json,
+          created_at,
+          read_at,
+          ack_json
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(parsed.id, parsed.fromMailbox, parsed.toMailbox, parsed.title, parsed.summary, parsed.body, JSON.stringify(parsed.tags), JSON.stringify(parsed.artifacts), JSON.stringify(parsed.payload), parsed.createdAt, parsed.readAt, JSON.stringify(parsed.ack));
+        return parsed;
+    }
+    async listInboxPreviews(mailboxName, options = {}) {
+        const parsedMailboxName = mailboxNameSchema.parse(mailboxName);
+        const limit = normalizeInboxPreviewLimit(options.limit);
+        const clauses = ["to_mailbox = ?"];
+        const params = [parsedMailboxName];
+        if (options.unreadOnly) {
+            clauses.push("read_at is null");
+        }
+        params.push(limit);
+        const rows = this.db
+            .prepare(`select * from context_packages
+         where ${clauses.join(" and ")}
+         order by created_at desc
+         limit ?`)
+            .all(...params);
+        return rows.map((row) => createContextPackagePreview(toContextPackage(row)));
+    }
+    async readContextPackage(id) {
+        const contextPackage = await this.getContextPackage(id);
+        if (!contextPackage) {
+            return null;
+        }
+        if (contextPackage.readAt) {
+            return contextPackage;
+        }
+        const readAt = new Date().toISOString();
+        this.db
+            .prepare("update context_packages set read_at = ? where id = ?")
+            .run(readAt, contextPackage.id);
+        return {
+            ...contextPackage,
+            readAt
+        };
+    }
+    async getContextPackage(id) {
+        const row = this.db
+            .prepare("select * from context_packages where id = ?")
+            .get(id);
+        return row ? toContextPackage(row) : null;
+    }
+    async ackContextPackage(id, options) {
+        const contextPackage = await this.getContextPackage(id);
+        if (!contextPackage) {
+            return null;
+        }
+        const ackBy = mailboxNameSchema.parse(options.ackBy);
+        const ack = {
+            status: "acknowledged",
+            ackAt: new Date().toISOString(),
+            ackBy,
+            note: options.note ?? null
+        };
+        this.db
+            .prepare("update context_packages set ack_json = ? where id = ?")
+            .run(JSON.stringify(ack), id);
+        return {
+            ...contextPackage,
+            ack
+        };
+    }
+    close() {
+        this.db.close();
+    }
+    async assertMailboxExists(name) {
+        const mailbox = await this.getMailbox(name);
+        if (!mailbox) {
+            throw new UnknownMailboxError(name);
+        }
+    }
+    migrate() {
+        // Context Packages reference mailboxes by name. Unknown recipients are
+        // rejected at storage time instead of being silently auto-created.
+        this.db.exec(`
+      create table if not exists mailboxes (
+        name text primary key,
+        created_at text not null,
+        last_seen_at text
+      );
+
+      create table if not exists context_packages (
+        id text primary key,
+        from_mailbox text not null references mailboxes(name),
+        to_mailbox text not null references mailboxes(name),
+        title text not null,
+        summary text not null,
+        body text not null,
+        tags_json text not null,
+        artifacts_json text not null,
+        payload_json text not null,
+        created_at text not null,
+        read_at text,
+        ack_json text not null
+      );
+
+      create index if not exists idx_context_packages_id
+        on context_packages (id);
+
+      create index if not exists idx_context_packages_inbox_created
+        on context_packages (to_mailbox, created_at desc);
+    `);
+    }
+}
+export class UnknownMailboxError extends Error {
+    mailboxName;
+    constructor(mailboxName) {
+        super(`Unknown mailbox: ${mailboxName}`);
+        this.mailboxName = mailboxName;
+        this.name = "UnknownMailboxError";
+    }
+}
+function toMailbox(row) {
+    // Validate rows on the way out so database changes cannot silently drift
+    // away from the public model contract.
+    return mailboxSchema.parse({
+        name: row.name,
+        createdAt: row.created_at,
+        lastSeenAt: row.last_seen_at
+    });
+}
+function toContextPackage(row) {
+    return contextPackageSchema.parse({
+        id: row.id,
+        fromMailbox: row.from_mailbox,
+        toMailbox: row.to_mailbox,
+        title: row.title,
+        summary: row.summary,
+        body: row.body,
+        tags: JSON.parse(row.tags_json),
+        artifacts: JSON.parse(row.artifacts_json),
+        payload: JSON.parse(row.payload_json),
+        createdAt: row.created_at,
+        readAt: row.read_at,
+        ack: JSON.parse(row.ack_json)
+    });
+}
+//# sourceMappingURL=sqlite-cimux-store.js.map

package/dist/storage/sqlite-cimux-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-cimux-store.js","sourceRoot":"","sources":["../../src/storage/sqlite-cimux-store.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "cimux";
+export declare const version = "0.1.0";

package/dist/version.js

@@ -0,0 +1,3 @@
+export const name = "cimux";
+export const version = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC;AAC5B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/docs/mvp-readiness.md

@@ -0,0 +1,85 @@
+# MVP Readiness
+
+This checklist defines the local Cimux MVP: agents can send intentional context to another local agent inbox; receivers can preview, read, and ack; empty inbox checks do not emit prompt context.
+
+## Automated Checks
+
+Run before every MVP release candidate:
+
+```bash
+npm test
+npm run typecheck
+npm run build
+npm run demo:local
+npm pack --dry-run
+```
+
+Expected result:
+
+- all tests pass
+- the demo sends, notifies, previews, reads, and acks one Context Package
+- the npm tarball includes `dist`, `README.md`, `package.json`, and `scripts/demo-local-handoff.mjs`
+
+## Manual Install Check
+
+Run this from the repo on a local machine:
+
+```bash
+npm install
+npm run build
+npm link
+cimux --help
+cimux --version
+cimux install --dry-run
+cimux install
+```
+
+Expected result:
+
+- `cimux --help` prints the command list
+- `cimux --version` prints the package version
+- `cimux install --dry-run` prints Codex and Claude config snippets
+- `cimux install` writes config and creates `.cimux.bak` backups before updating existing files
+- a new Codex or Claude session sees the Cimux MCP server after restart
+
+## Harness Verification
+
+After installing and restarting the target harness:
+
+1. Confirm the Cimux MCP tools are visible:
+   - `register_session`
+   - `send_context`
+   - `check_inbox`
+   - `read_context`
+   - `ack_context`
+2. Start or resume a session in a git repo.
+3. Confirm the session can register as `harness/branch-name`.
+4. Send a Context Package to that mailbox.
+5. Submit a new user prompt to the receiving session.
+6. Confirm the hook emits one short notification line.
+7. Confirm `check_inbox` returns previews only.
+8. Confirm `read_context` returns the full body.
+9. Confirm `ack_context` marks the package acknowledged.
+
+## Known Limits
+
+- Local-only SQLite storage.
+- No hosted auth, workspaces, or SaaS tenancy.
+- No vector database or embeddings.
+- No automatic routing.
+- No remote mailbox sync.
+- No read-only inspector UI yet.
+- Hook notification depends on harness hook support and fires on the next user prompt, not as a real-time interrupt.
+- The installer targets the first supported Codex and Claude config paths and may need more harness-specific hardening before a public release.
+
+## MVP Complete Bar
+
+Call the local MVP complete when:
+
+- automated checks pass
+- local demo passes
+- manual install check passes on one machine
+- at least one harness can see the MCP tools after install/restart
+- hook notification is verified in that harness
+- README and this checklist match the observed behavior
+

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "cimux-mcp",
+  "version": "0.1.0",
+  "description": "Local-first mailbox for intentional AI agent context handoffs.",
+  "keywords": [
+    "mcp",
+    "agents",
+    "context",
+    "mailbox",
+    "codex",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jackkslash/cimux.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jackkslash/cimux/issues"
+  },
+  "homepage": "https://github.com/jackkslash/cimux#readme",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "cimux": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "scripts"
+  ],
+  "scripts": {
+    "clean": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "demo:local": "npm run build && node scripts/demo-local-handoff.mjs",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.14",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}

package/scripts/demo-local-handoff.mjs

@@ -0,0 +1,73 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "cimux-demo-"));
+const dbPath = path.join(tempDir, "cimux.sqlite");
+const cliPath = path.join(process.cwd(), "dist", "index.js");
+
+function run(args) {
+  return execFileSync(process.execPath, [cliPath, ...args], {
+    cwd: tempDir,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      CIMUX_DB_PATH: dbPath
+    }
+  }).trim();
+}
+
+function runJson(args) {
+  return JSON.parse(run(args));
+}
+
+console.log("Cimux local handoff demo");
+console.log(`Database: ${dbPath}`);
+
+run(["register", "--mailbox", "codex/backend-auth"]);
+run(["register", "--mailbox", "claude/frontend-login"]);
+
+const sent = runJson([
+  "send",
+  "--from",
+  "codex/backend-auth",
+  "--to",
+  "claude/frontend-login",
+  "--title",
+  "Auth handoff",
+  "--summary",
+  "Frontend should handle the new auth error.",
+  "--body",
+  "validateSession now throws ExpiredSessionError.",
+  "--tags",
+  "auth,frontend"
+]);
+
+console.log(`Sent: ${sent.contextPackage.id}`);
+console.log(run(["notify", "--mailbox", "claude/frontend-login"]));
+
+const inbox = runJson(["check", "--mailbox", "claude/frontend-login"]);
+console.log(`Preview count: ${inbox.previews.length}`);
+console.log(`Preview title: ${inbox.previews[0].title}`);
+
+const read = runJson([
+  "read",
+  "--mailbox",
+  "claude/frontend-login",
+  "--id",
+  sent.contextPackage.id
+]);
+console.log(`Read body: ${read.contextPackage.body}`);
+
+const acked = runJson([
+  "ack",
+  "--mailbox",
+  "claude/frontend-login",
+  "--id",
+  sent.contextPackage.id,
+  "--note",
+  "Loaded in demo."
+]);
+console.log(`Ack: ${acked.contextPackage.ack.status}`);
+