@neethan/joa 0.1.0

package/dist/core/index.js

@@ -0,0 +1,19 @@
+// Error classes — exported so callers can catch by type
+export { JoaError, ValidationError, InvalidThreadId, DatabaseError, JournalWriteError, ConfigError, } from "./errors.js";
+// Entry serialization
+export { serializeEntry } from "./entry.js";
+// Import
+export { importEntries } from "./import.js";
+// Operations
+export { log } from "./log.js";
+export { query } from "./query.js";
+export { status } from "./status.js";
+// Storage lifecycle
+export { openDatabase } from "./db.js";
+export { checkAndSyncIfStale, rebuildIndex } from "./sync.js";
+// Config
+export { loadConfig, defaultConfig, getDevice, resolveDbPath, resolveJournalsPath, } from "./config.js";
+// IDs (needed by MCP session management in 1B)
+export { sessionId, entryId, threadId } from "./ids.js";
+// Bootstrap
+export { bootstrap, validateAgentName } from "./bootstrap.js";

package/dist/core/journal.js

@@ -0,0 +1,65 @@
+import { appendFile, mkdir, readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { serializeEntry } from "./entry.js";
+import { JournalWriteError } from "./errors.js";
+import { todayDate } from "./time.js";
+/**
+ * Appends a single entry to the date-based JSONL file.
+ * Uses O_APPEND semantics — atomic for entries < ~4KB on local POSIX filesystems.
+ * Creates the journals directory if it does not exist.
+ */
+export async function appendEntry(entry, journalsDir) {
+    try {
+        await mkdir(journalsDir, { recursive: true });
+        const filename = `${todayDate()}.jsonl`;
+        const filePath = join(journalsDir, filename);
+        const line = `${JSON.stringify(serializeEntry(entry))}\n`;
+        await appendFile(filePath, line, "utf8");
+    }
+    catch (cause) {
+        throw new JournalWriteError("Failed to append entry to journal", { cause });
+    }
+}
+/**
+ * Lists all YYYY-MM-DD.jsonl files in journalsDir, sorted by date ascending.
+ * Returns empty array if directory does not exist.
+ */
+export async function listJournalFiles(journalsDir) {
+    try {
+        const files = await readdir(journalsDir);
+        return files
+            .filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f))
+            .sort()
+            .map((f) => join(journalsDir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Reads all valid entry rows from a single JSONL file.
+ * Skips malformed lines (logs a warning to stderr). Never throws on parse errors.
+ */
+export async function readJournalFile(filePath) {
+    const content = await readFile(filePath, "utf8");
+    const lines = content.split("\n").filter((l) => l.trim().length > 0);
+    const entries = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                typeof parsed.id !== "string" ||
+                typeof parsed.summary !== "string") {
+                console.warn(`Skipping invalid entry in ${filePath}: missing required fields: ${line.slice(0, 80)}`);
+                continue;
+            }
+            const row = parsed;
+            entries.push(row);
+        }
+        catch {
+            console.warn(`Skipping malformed JSONL line in ${filePath}: ${line.slice(0, 80)}`);
+        }
+    }
+    return entries;
+}

package/dist/core/log.js

@@ -0,0 +1,49 @@
+import { normalizeCategory, validateEntryInput } from "./entry.js";
+import { entryId, threadId as generateThreadId } from "./ids.js";
+import { appendEntry } from "./journal.js";
+import { nowUtc } from "./time.js";
+function resolveThreadId(tid) {
+    if (tid === undefined || tid === null)
+        return null;
+    if (tid === "new")
+        return generateThreadId();
+    return tid; // already validated by validateEntryInput
+}
+/** Write a journal entry. JSONL first (source of truth), then SQLite (derived index). */
+export async function log(input, ctx) {
+    // 1. Validate before any I/O
+    validateEntryInput(input);
+    // 2. Resolve thread_id
+    const resolvedThreadId = resolveThreadId(input.thread_id);
+    // 3. Build entry
+    const entry = {
+        id: entryId(),
+        timestamp: nowUtc(),
+        category: normalizeCategory(input.category),
+        summary: input.summary.trim(),
+        thread_id: resolvedThreadId,
+        session_id: ctx.sessionId,
+        agent: ctx.agent,
+        device: ctx.device,
+        resources: input.resources ?? [],
+        tags: [...new Set([...(input.tags ?? []), ...ctx.defaultTags])],
+        detail: input.detail ?? {},
+        annotations: input.annotations ?? {},
+    };
+    // 4. JSONL first — source of truth
+    await appendEntry(entry, ctx.journalsDir);
+    // 5. SQLite second — derived index
+    try {
+        ctx.db.writeEntry(entry);
+    }
+    catch {
+        // Entry is durable in JSONL; index will recover on next startup
+        return {
+            entry_id: entry.id,
+            thread_id: entry.thread_id,
+            status: "ok",
+            warning: "index_sync_failed",
+        };
+    }
+    return { entry_id: entry.id, thread_id: entry.thread_id, status: "ok" };
+}

package/dist/core/query.js

@@ -0,0 +1,114 @@
+import { deserializeEntry } from "./entry.js";
+import { formatCompact, formatJson, formatMd } from "./formatters.js";
+import { parseSince } from "./time.js";
+const MAX_LIMIT = 1000;
+const MAX_SEARCH_LENGTH = 500;
+/** Truncate to at most `max` Unicode codepoints without splitting surrogate pairs. */
+function unicodeTruncate(s, max) {
+    if (s.length <= max)
+        return s;
+    let count = 0;
+    let i = 0;
+    while (i < s.length && count < max) {
+        const code = s.codePointAt(i) ?? 0;
+        i += code > 0xffff ? 2 : 1;
+        count++;
+    }
+    return s.slice(0, i);
+}
+/** Escape FTS5 special characters by wrapping in double quotes. */
+function escapeFts(query) {
+    // Strip null bytes — they cause "unterminated string" in FTS5
+    const clean = query.replace(/\0/g, "");
+    return `"${clean.replace(/"/g, '""')}"`;
+}
+function formatThreadSummary(threads) {
+    if (threads.length === 0)
+        return "No active threads.";
+    return threads
+        .map((t) => {
+        const agents = t.agents ? ` (${t.agents})` : "";
+        return `- **${t.first_summary}**\n  Thread: ${t.thread_id} \u00b7 ${t.entry_count} entries \u00b7 Last active: ${t.last_active_at}${agents}`;
+    })
+        .join("\n\n");
+}
+/** Query entries with optional preset, filters, and formatting. */
+export function query(input, ctx, config) {
+    const format = input.format ?? "md";
+    const presetConfig = input.preset ? config.presets[input.preset] : undefined;
+    // Threads preset is special — uses the thread_summary view
+    if (input.preset === "threads") {
+        const limit = input.limit ?? presetConfig?.thread_limit ?? 20;
+        const threads = ctx.db.queryThreadSummary(limit);
+        const rendered = formatThreadSummary(threads);
+        return {
+            entries: [],
+            rendered,
+            total: threads.length,
+            format,
+        };
+    }
+    // Build query params from preset + direct input
+    const params = {};
+    // Apply preset defaults
+    if (input.preset === "catchup") {
+        params.since = parseSince("7d");
+        params.limit = input.limit ?? presetConfig?.default_limit ?? 50;
+    }
+    else if (input.preset === "timeline") {
+        params.limit = input.limit ?? presetConfig?.default_limit ?? 50;
+    }
+    else if (input.preset === "decisions") {
+        params.category = "decision";
+        params.limit = input.limit ?? presetConfig?.default_limit ?? 50;
+    }
+    else if (input.preset === "changes") {
+        params.category = "file change";
+        params.limit = input.limit ?? presetConfig?.default_limit ?? 50;
+    }
+    // Direct params override preset defaults
+    if (input.thread_id)
+        params.thread_id = input.thread_id;
+    if (input.session_id)
+        params.session_id = input.session_id;
+    if (input.category)
+        params.category = input.category.trim().toLowerCase();
+    if (input.agent)
+        params.agent = input.agent;
+    if (input.device)
+        params.device = input.device;
+    if (input.tags)
+        params.tags = input.tags;
+    if (input.since)
+        params.since = parseSince(input.since);
+    if (input.until)
+        params.until = parseSince(input.until);
+    if (input.limit !== undefined)
+        params.limit = input.limit;
+    params.limit = Math.min(params.limit ?? 50, MAX_LIMIT);
+    // FTS search — escape special chars, truncate long queries (Unicode-safe)
+    if (input.search) {
+        const trimmed = unicodeTruncate(input.search, MAX_SEARCH_LENGTH);
+        params.search = escapeFts(trimmed);
+    }
+    // Get total count (before limit)
+    const countParams = { ...params };
+    countParams.limit = undefined;
+    const total = ctx.db.countEntries(countParams);
+    // Query entries
+    const rows = ctx.db.queryEntries(params);
+    const entries = rows.map(deserializeEntry);
+    // Format output
+    let rendered;
+    switch (format) {
+        case "json":
+            rendered = formatJson(entries);
+            break;
+        case "compact":
+            rendered = formatCompact(entries);
+            break;
+        default:
+            rendered = formatMd(entries);
+    }
+    return { entries, rendered, total, format };
+}

package/dist/core/status.js

@@ -0,0 +1,30 @@
+import { readdirSync } from "node:fs";
+import { resolveDbPath, resolveJournalsPath } from "./config.js";
+/** Returns journal health and stats. */
+export function status(ctx, config, sessionId) {
+    const entriesByCategory = ctx.db.countByCategory();
+    const totalEntries = Object.values(entriesByCategory).reduce((sum, n) => sum + n, 0);
+    const range = ctx.db.getEntryTimestampRange();
+    const dbPath = resolveDbPath(config);
+    const journalsDir = resolveJournalsPath(config);
+    let journalFiles = 0;
+    try {
+        const files = readdirSync(journalsDir);
+        journalFiles = files.filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)).length;
+    }
+    catch {
+        // Directory doesn't exist yet
+    }
+    return {
+        total_entries: totalEntries,
+        entries_by_category: entriesByCategory,
+        oldest_entry: range.oldest,
+        newest_entry: range.newest,
+        current_session_id: sessionId,
+        db_path: dbPath,
+        journals_dir: journalsDir,
+        journal_files: journalFiles,
+        db_healthy: ctx.db.isHealthy(),
+        db_size_bytes: ctx.db.getDbSizeBytes(),
+    };
+}

package/dist/core/sync.js

@@ -0,0 +1,94 @@
+import { statSync } from "node:fs";
+import { deserializeEntry } from "./entry.js";
+import { listJournalFiles, readJournalFile } from "./journal.js";
+/**
+ * Called on every process startup after openDatabase().
+ * Checks JSONL file modification times against last_indexed_at in metadata.
+ * Performs incremental rebuild if any file is newer.
+ */
+export async function checkAndSyncIfStale(db, journalsDir) {
+    const lastIndexed = db.getLastIndexedAt();
+    const files = await listJournalFiles(journalsDir);
+    if (files.length === 0)
+        return;
+    const lastIndexedMs = lastIndexed ? new Date(lastIndexed).getTime() : 0;
+    const staleFiles = files.filter((f) => {
+        try {
+            const mtime = statSync(f).mtimeMs;
+            return mtime > lastIndexedMs;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (staleFiles.length === 0)
+        return;
+    // Capture max mtime of stale files BEFORE processing to avoid data loss window
+    let maxMtimeMs = 0;
+    for (const f of staleFiles) {
+        try {
+            const mtime = statSync(f).mtimeMs;
+            if (mtime > maxMtimeMs)
+                maxMtimeMs = mtime;
+        }
+        catch {
+            /* already filtered */
+        }
+    }
+    for (const file of staleFiles) {
+        const rows = await readJournalFile(file);
+        const entries = [];
+        for (const row of rows) {
+            try {
+                entries.push(deserializeEntry(row));
+            }
+            catch {
+                console.warn(`Skipping entry during sync: ${row.id}`);
+            }
+        }
+        if (entries.length > 0) {
+            db.writeEntries(entries);
+        }
+    }
+    // Use the max mtime instead of nowUtc() to avoid missing files modified during sync
+    db.setLastIndexedAt(new Date(maxMtimeMs).toISOString());
+}
+/**
+ * Full reconstruction of SQLite entries + FTS from all JSONL files.
+ * For use when the index is corrupted or during joa rebuild.
+ */
+export async function rebuildIndex(db, journalsDir) {
+    db.clearEntries();
+    const files = await listJournalFiles(journalsDir);
+    // Capture max mtime of all files BEFORE processing
+    let maxMtimeMs = 0;
+    for (const f of files) {
+        try {
+            const mtime = statSync(f).mtimeMs;
+            if (mtime > maxMtimeMs)
+                maxMtimeMs = mtime;
+        }
+        catch {
+            /* skip unreadable files */
+        }
+    }
+    for (const file of files) {
+        const rows = await readJournalFile(file);
+        const entries = [];
+        for (const row of rows) {
+            try {
+                entries.push(deserializeEntry(row));
+            }
+            catch {
+                console.warn(`Skipping entry during rebuild: ${row.id}`);
+            }
+        }
+        if (entries.length > 0) {
+            db.writeEntries(entries);
+        }
+    }
+    db.rebuildFts();
+    if (maxMtimeMs > 0) {
+        db.setLastIndexedAt(new Date(maxMtimeMs).toISOString());
+    }
+}

package/dist/core/time.js

@@ -0,0 +1,50 @@
+import { ValidationError } from "./errors.js";
+const RELATIVE_RE = /^(\d+)([dwm])$/;
+/**
+ * Parses a time string into an ISO 8601 UTC timestamp.
+ * Accepts: relative ("1d", "7d", "2w", "1m") or ISO date/datetime strings.
+ */
+export function parseSince(since) {
+    const match = since.match(RELATIVE_RE);
+    if (match) {
+        const amount = Number.parseInt(match[1] ?? "0", 10);
+        const unit = match[2] ?? "d";
+        const now = Date.now();
+        let ms;
+        switch (unit) {
+            case "d":
+                ms = amount * 24 * 60 * 60 * 1000;
+                break;
+            case "w":
+                ms = amount * 7 * 24 * 60 * 60 * 1000;
+                break;
+            case "m":
+                ms = amount * 30 * 24 * 60 * 60 * 1000;
+                break;
+            default:
+                ms = 0;
+        }
+        return new Date(now - ms).toISOString();
+    }
+    // ISO date "YYYY-MM-DD" → start of that UTC day
+    if (/^\d{4}-\d{2}-\d{2}$/.test(since)) {
+        return `${since}T00:00:00.000Z`;
+    }
+    // ISO datetime — validate before pass through
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(since)) {
+        throw new ValidationError(`Invalid ISO 8601 timestamp: "${since}". Expected format: YYYY-MM-DDTHH:mm:ss.sssZ or YYYY-MM-DDTHH:mm:ssZ`);
+    }
+    return since;
+}
+/** Returns today's date as "YYYY-MM-DD" using local system time. */
+export function todayDate() {
+    const now = new Date();
+    const y = now.getFullYear();
+    const m = String(now.getMonth() + 1).padStart(2, "0");
+    const d = String(now.getDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+}
+/** Returns the current UTC timestamp as ISOTimestamp. */
+export function nowUtc() {
+    return new Date().toISOString();
+}

package/dist/mcp/server.js

@@ -0,0 +1,149 @@
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { bootstrap, log, query, status } from "../core/index.js";
+const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function textContent(text) {
+    return { content: [{ type: "text", text }] };
+}
+function errorResponse(toolName, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`${toolName} error: ${message}`);
+    return { ...textContent(`Error: ${message}`), isError: true };
+}
+// Agent name is set by the CLI dispatcher via JOA_MCP_AGENT env var
+// before dynamic-importing this module (see src/cli/main.ts "mcp" case).
+const { config, readCtx, logCtx, sid } = await bootstrap({
+    agent: process.env.JOA_MCP_AGENT ?? "mcp",
+});
+const server = new McpServer({
+    name: "joa",
+    version: pkg.version,
+});
+// ---------------------------------------------------------------------------
+// joa_log
+// ---------------------------------------------------------------------------
+server.registerTool("joa_log", {
+    title: "Log Entry",
+    description: "Log a journal entry to joa. Records observations, decisions, file changes, and other agent activity.",
+    inputSchema: {
+        category: z.string().describe("Entry category (e.g. observation, decision, file change)"),
+        summary: z.string().describe("Short summary of the entry"),
+        thread_id: z
+            .union([z.literal("new"), z.string().startsWith("th_")])
+            .nullable()
+            .optional()
+            .describe("Thread ID or 'new' to start a thread"),
+        detail: z.record(z.string(), z.unknown()).optional().describe("Additional structured detail"),
+        resources: z
+            .array(z.string())
+            .optional()
+            .describe("File paths or URLs related to this entry"),
+        tags: z.array(z.string()).optional().describe("Tags for categorization"),
+        annotations: z.record(z.string(), z.unknown()).optional().describe("Metadata annotations"),
+    },
+}, async (args) => {
+    try {
+        const result = await log({
+            category: args.category,
+            summary: args.summary,
+            thread_id: args.thread_id,
+            detail: args.detail,
+            resources: args.resources,
+            tags: args.tags,
+            annotations: args.annotations,
+        }, logCtx);
+        return textContent(JSON.stringify({
+            entry_id: result.entry_id,
+            thread_id: result.thread_id,
+            status: result.status,
+            ...(result.warning ? { warning: result.warning } : {}),
+        }));
+    }
+    catch (err) {
+        return errorResponse("joa_log", err);
+    }
+});
+// ---------------------------------------------------------------------------
+// joa_query
+// ---------------------------------------------------------------------------
+server.registerTool("joa_query", {
+    title: "Query Entries",
+    description: "Query journal entries from joa. Supports presets (catchup, threads, timeline, decisions, changes), full-text search, and filters.",
+    inputSchema: {
+        preset: z
+            .enum(["catchup", "threads", "timeline", "decisions", "changes"])
+            .optional()
+            .describe("Query preset"),
+        thread_id: z.string().optional().describe("Filter by thread ID"),
+        session_id: z.string().optional().describe("Filter by session ID"),
+        category: z.string().optional().describe("Filter by category"),
+        agent: z.string().optional().describe("Filter by agent name"),
+        device: z.string().optional().describe("Filter by device name"),
+        search: z.string().optional().describe("Full-text search term"),
+        tags: z.array(z.string()).optional().describe("Filter by tags (AND semantics)"),
+        since: z.string().optional().describe("Time filter: 1d, 7d, 2w, 1m, or ISO date"),
+        until: z.string().optional().describe("Time upper bound"),
+        limit: z.number().int().min(1).max(1000).optional().describe("Max entries to return"),
+        format: z.enum(["md", "json", "compact"]).optional().describe("Output format (default: md)"),
+    },
+}, async (args) => {
+    try {
+        const result = query({
+            preset: args.preset,
+            thread_id: args.thread_id,
+            session_id: args.session_id,
+            category: args.category,
+            agent: args.agent,
+            device: args.device,
+            search: args.search,
+            tags: args.tags,
+            since: args.since,
+            until: args.until,
+            limit: args.limit,
+            format: args.format ?? "md",
+        }, readCtx, config);
+        let text = result.rendered;
+        if (result.total > result.entries.length) {
+            text += `\n\n_Showing ${result.entries.length} of ${result.total} entries_`;
+        }
+        return textContent(text);
+    }
+    catch (err) {
+        return errorResponse("joa_query", err);
+    }
+});
+// ---------------------------------------------------------------------------
+// joa_status
+// ---------------------------------------------------------------------------
+server.registerTool("joa_status", {
+    title: "Journal Status",
+    description: "Get journal health stats: entry count, categories, timestamps, DB health.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const s = status(readCtx, config, sid);
+        return textContent(JSON.stringify(s, null, 2));
+    }
+    catch (err) {
+        return errorResponse("joa_status", err);
+    }
+});
+// ---------------------------------------------------------------------------
+// Start transport
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("joa MCP server started");
+// Clean shutdown
+function shutdown() {
+    console.error("joa MCP server shutting down");
+    logCtx.db.close();
+    process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@neethan/joa",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Journal of Agents — persistent activity journal for AI agents",
+  "bin": {
+    "joa": "dist/cli/main.js"
+  },
+  "files": ["dist/"],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "neethan <neethan@hallid.ai> (https://github.com/neethanwu)",
+  "homepage": "https://github.com/neethanwu/joa#readme",
+  "bugs": {
+    "url": "https://github.com/neethanwu/joa/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neethanwu/joa.git"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "journal",
+    "mcp",
+    "memory",
+    "claude",
+    "cursor",
+    "llm",
+    "activity-log"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && test -s dist/cli/main.js && printf '#!/usr/bin/env node\\n' | cat - dist/cli/main.js > dist/cli/main.tmp && mv dist/cli/main.tmp dist/cli/main.js && chmod +x dist/cli/main.js",
+    "prepublishOnly": "bun run build",
+    "lint": "bunx biome check .",
+    "lint:fix": "bunx biome check --write .",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "better-sqlite3": "^12.6.2",
+    "js-yaml": "^4.1.0",
+    "ulidx": "^2.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.3.1",
+    "bun-types": "^1.3.9",
+    "typescript": "^5.7.0"
+  },
+  "trustedDependencies": ["@biomejs/biome", "better-sqlite3"]
+}