agentgather 0.1.0

package/dist/src/storage/lock.js

@@ -0,0 +1,93 @@
+import { chmod, open, readFile, rm, stat } from "node:fs/promises";
+import { SECURE_FILE_MODE } from "./secure-fs.js";
+export async function withWriterLock(lockPath, fn, options = {}) {
+    const release = await acquireWriterLock(lockPath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+async function acquireWriterLock(lockPath, options) {
+    const retryDelayMs = options.retryDelayMs ?? 10;
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const staleAfterMs = options.staleAfterMs ?? 30_000;
+    const startedAt = Date.now();
+    const record = { pid: process.pid, createdAt: new Date().toISOString() };
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx", SECURE_FILE_MODE);
+            await handle.writeFile(JSON.stringify(record));
+            await handle.close();
+            await chmod(lockPath, SECURE_FILE_MODE);
+            return async () => {
+                await rm(lockPath, { force: true });
+            };
+        }
+        catch (error) {
+            if (!isFileExistsError(error))
+                throw error;
+            if (Date.now() - startedAt > timeoutMs) {
+                throw new Error(`timed out waiting for writer lock: ${lockPath}`);
+            }
+            if (await removeStaleLock(lockPath, staleAfterMs))
+                continue;
+            await sleep(retryDelayMs);
+        }
+    }
+}
+async function removeStaleLock(lockPath, staleAfterMs) {
+    try {
+        const raw = await readFile(lockPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== "number") {
+            return removeMalformedLockIfOld(lockPath, staleAfterMs);
+        }
+        if (!isProcessAlive(parsed.pid)) {
+            await rm(lockPath, { force: true });
+            return true;
+        }
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return false;
+        return removeMalformedLockIfOld(lockPath, staleAfterMs);
+    }
+    return false;
+}
+async function removeMalformedLockIfOld(lockPath, staleAfterMs) {
+    try {
+        const info = await stat(lockPath);
+        if (Date.now() - info.mtimeMs < staleAfterMs)
+            return false;
+    }
+    catch (error) {
+        return isNotFoundError(error);
+    }
+    await rm(lockPath, { force: true });
+    return true;
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isNoSuchProcessError(error);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function isFileExistsError(error) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+function isNotFoundError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isNoSuchProcessError(error) {
+    return error instanceof Error && "code" in error && error.code === "ESRCH";
+}

package/dist/src/storage/paths.js

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { assertSafeSlug } from "../protocol/validation.js";
+export function roomPaths(root, roomId) {
+    assertSafeSlug(roomId, "room id");
+    const rooms = path.join(root, "rooms");
+    const room = path.join(rooms, roomId);
+    return {
+        root,
+        rooms,
+        room,
+        state: path.join(room, "room.json"),
+        participants: path.join(room, "participants.json"),
+        brief: path.join(room, "brief.md"),
+        messages: path.join(room, "messages.jsonl"),
+        cursors: path.join(room, "cursors"),
+        lock: path.join(room, "write.lock")
+    };
+}

package/dist/src/storage/room-store.js

@@ -0,0 +1,302 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { assertSafeSlug, buildMessage, clientMessageInputFromRecord, parseMentions } from "../protocol/index.js";
+import { withWriterLock } from "./lock.js";
+import { roomPaths } from "./paths.js";
+import { appendSecureFile, ensureSecureDir, writeSecureFile } from "./secure-fs.js";
+export const MAX_BRIEF_LENGTH = 16_000;
+export class RoomLogFullError extends Error {
+    constructor() {
+        super("room message log is full");
+    }
+}
+export async function createRoom(options) {
+    assertSafeSlug(options.roomId, "room id");
+    assertSafeSlug(options.hostAlias, "host alias");
+    const now = options.now ?? new Date();
+    const paths = roomPaths(options.root, options.roomId);
+    await ensureRoomDirectories(paths);
+    const briefBody = options.briefBody ?? "";
+    assertBriefSize(briefBody);
+    const state = {
+        id: options.roomId,
+        status: "open",
+        attendance_policy: options.attendancePolicy ?? "manual-ok",
+        createdAt: now.toISOString(),
+        updatedAt: now.toISOString(),
+        next_message_id: 1,
+        brief_version: 1,
+        brief_updated_at: now.toISOString(),
+        brief_updated_by: options.hostAlias
+    };
+    if (options.expiresAt !== undefined) {
+        state.expires_at = options.expiresAt.toISOString();
+    }
+    await writeNewJson(paths.state, state);
+    await writeNewJson(paths.participants, []);
+    await writeSecureFile(paths.brief, briefBody, { flag: "wx" });
+    await writeSecureFile(paths.messages, "", { flag: "wx" });
+    return state;
+}
+export async function updateAttendancePolicy(options) {
+    assertSafeSlug(options.roomId, "room id");
+    assertSafeSlug(options.updatedBy, "updated by");
+    const now = options.now ?? new Date();
+    const paths = roomPaths(options.root, options.roomId);
+    return withWriterLock(paths.lock, async () => {
+        const state = withRoomDefaults(await readRoomState(paths));
+        const updatedState = {
+            ...state,
+            attendance_policy: options.policy,
+            updatedAt: now.toISOString()
+        };
+        await writeJson(paths.state, updatedState);
+        return updatedState;
+    });
+}
+export async function updateBrief(options) {
+    assertSafeSlug(options.roomId, "room id");
+    assertSafeSlug(options.updatedBy, "updated by");
+    assertBriefSize(options.body);
+    const now = options.now ?? new Date();
+    const paths = roomPaths(options.root, options.roomId);
+    return withWriterLock(paths.lock, async () => {
+        const state = await readRoomState(paths);
+        const updatedState = {
+            ...state,
+            updatedAt: now.toISOString(),
+            brief_version: state.brief_version + 1,
+            brief_updated_at: now.toISOString(),
+            brief_updated_by: options.updatedBy
+        };
+        await writeSecureFile(paths.brief, options.body);
+        await writeJson(paths.state, updatedState);
+        return {
+            body: options.body,
+            brief_version: updatedState.brief_version,
+            brief_updated_at: updatedState.brief_updated_at,
+            brief_updated_by: updatedState.brief_updated_by
+        };
+    });
+}
+export async function appendMessage(options) {
+    return (await appendMessageResult(options)).message;
+}
+export async function appendMessageResult(options) {
+    assertSafeSlug(options.roomId, "room id");
+    assertSafeSlug(options.from, "from");
+    const paths = roomPaths(options.root, options.roomId);
+    const input = clientMessageInputFromRecord(options.input);
+    const now = options.now ?? new Date();
+    return withWriterLock(paths.lock, async () => {
+        const state = await readRoomState(paths);
+        const participants = await readParticipants(paths);
+        const messages = await readJsonLines(paths.messages);
+        if (input.client_msg_id !== undefined) {
+            const existing = messages.find((message) => message.from === options.from && message.client_msg_id === input.client_msg_id);
+            if (existing !== undefined)
+                return { message: existing, idempotent: true };
+        }
+        if (options.maxMessages !== undefined && messages.length >= options.maxMessages) {
+            throw new RoomLogFullError();
+        }
+        const message = createMessage(input, {
+            id: state.next_message_id,
+            room: state.id,
+            from: options.from,
+            roster: participants.map((participant) => participant.alias),
+            now
+        });
+        await appendJsonLine(paths.messages, message);
+        await writeJson(paths.state, {
+            ...state,
+            updatedAt: now.toISOString(),
+            next_message_id: message.id + 1
+        });
+        return { message, idempotent: false };
+    });
+}
+export async function appendServerMessage(options) {
+    assertSafeSlug(options.roomId, "room id");
+    assertSafeSlug(options.from, "from");
+    const paths = roomPaths(options.root, options.roomId);
+    const now = options.now ?? new Date();
+    return withWriterLock(paths.lock, async () => {
+        const state = await readRoomState(paths);
+        const participants = await readParticipants(paths);
+        const message = buildMessage({ text: options.text }, {
+            id: state.next_message_id,
+            room: state.id,
+            from: options.from,
+            now,
+            mentions: parseMentions(options.text, participants.map((participant) => participant.alias)),
+            type: "system"
+        });
+        await appendJsonLine(paths.messages, message);
+        await writeJson(paths.state, {
+            ...state,
+            updatedAt: now.toISOString(),
+            next_message_id: message.id + 1
+        });
+        return message;
+    });
+}
+export async function readMessages(root, roomId) {
+    const paths = roomPaths(root, roomId);
+    return readJsonLines(paths.messages);
+}
+export async function readBrief(root, roomId) {
+    const paths = roomPaths(root, roomId);
+    const [state, body] = await Promise.all([readRoomState(paths), readFile(paths.brief, "utf8")]);
+    return {
+        body,
+        brief_version: state.brief_version,
+        brief_updated_at: state.brief_updated_at,
+        brief_updated_by: state.brief_updated_by
+    };
+}
+export async function readCursor(root, roomId, alias) {
+    assertSafeSlug(alias, "alias");
+    const paths = roomPaths(root, roomId);
+    try {
+        const record = await readJson(cursorPath(paths, alias));
+        return record.sinceId;
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return 0;
+        throw error;
+    }
+}
+export async function writeCursor(root, roomId, alias, sinceId, now = new Date()) {
+    assertSafeSlug(alias, "alias");
+    if (!Number.isSafeInteger(sinceId) || sinceId < 0) {
+        throw new Error("cursor sinceId must be a non-negative safe integer");
+    }
+    const paths = roomPaths(root, roomId);
+    await ensureSecureDir(paths.cursors);
+    const record = {
+        alias,
+        sinceId,
+        updatedAt: now.toISOString()
+    };
+    await writeJson(cursorPath(paths, alias), record);
+    return record;
+}
+export async function writeParticipants(root, roomId, participants) {
+    const paths = roomPaths(root, roomId);
+    for (const participant of participants) {
+        assertSafeSlug(participant.alias, "participant alias");
+    }
+    await withWriterLock(paths.lock, async () => {
+        await writeJson(paths.participants, participants);
+    });
+}
+export async function upsertParticipant(root, roomId, participant) {
+    assertSafeSlug(participant.alias, "participant alias");
+    const paths = roomPaths(root, roomId);
+    await withWriterLock(paths.lock, async () => {
+        const participants = await readParticipants(paths);
+        const existingIndex = participants.findIndex((current) => current.alias === participant.alias);
+        if (existingIndex === -1) {
+            participants.push(participant);
+        }
+        else {
+            participants[existingIndex] = participant;
+        }
+        await writeJson(paths.participants, participants);
+    });
+}
+export async function closeRoom(root, roomId, now = new Date()) {
+    const paths = roomPaths(root, roomId);
+    return withWriterLock(paths.lock, async () => {
+        const state = await readRoomState(paths);
+        const closed = {
+            ...state,
+            status: "closed",
+            updatedAt: now.toISOString()
+        };
+        await writeJson(paths.state, closed);
+        return closed;
+    });
+}
+export async function readRoomState(paths) {
+    return withRoomDefaults(await readJson(paths.state));
+}
+export async function readParticipants(paths) {
+    return readJson(paths.participants);
+}
+export async function recoverNextMessageId(messagesPath) {
+    const messages = await readJsonLines(messagesPath);
+    return messages.reduce((highest, message) => Math.max(highest, message.id), 0) + 1;
+}
+export async function recoverRoomState(root, roomId) {
+    const paths = roomPaths(root, roomId);
+    return withWriterLock(paths.lock, async () => {
+        const state = await readRoomState(paths);
+        const recoveredNextId = await recoverNextMessageId(paths.messages);
+        if (state.next_message_id >= recoveredNextId)
+            return state;
+        const recoveredState = {
+            ...state,
+            next_message_id: recoveredNextId
+        };
+        await writeJson(paths.state, recoveredState);
+        return recoveredState;
+    });
+}
+function createMessage(input, options) {
+    return buildMessage(input, {
+        id: options.id,
+        room: options.room,
+        from: options.from,
+        now: options.now,
+        mentions: parseMentions(input.text, options.roster)
+    });
+}
+async function ensureRoomDirectories(paths) {
+    await ensureSecureDir(paths.root);
+    await ensureSecureDir(paths.rooms);
+    await ensureSecureDir(paths.room);
+    await ensureSecureDir(paths.cursors);
+}
+function assertBriefSize(body) {
+    if (body.length > MAX_BRIEF_LENGTH) {
+        throw new Error(`brief body must be <= ${MAX_BRIEF_LENGTH} characters`);
+    }
+}
+async function appendJsonLine(path, value) {
+    const line = `${JSON.stringify(value)}\n`;
+    await appendSecureFile(path, line);
+}
+async function readJson(path) {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+}
+async function writeJson(path, value) {
+    await writeSecureFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+function withRoomDefaults(state) {
+    return {
+        ...state,
+        attendance_policy: state.attendance_policy ?? "manual-ok"
+    };
+}
+async function writeNewJson(path, value) {
+    await writeSecureFile(path, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx" });
+}
+async function readJsonLines(path) {
+    const raw = await readFile(path, "utf8");
+    if (raw.trim().length === 0)
+        return [];
+    return raw
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line));
+}
+function cursorPath(paths, alias) {
+    return path.join(paths.cursors, `${alias}.json`);
+}
+function isNotFoundError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/dist/src/storage/secure-fs.js

@@ -0,0 +1,28 @@
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const SECURE_DIR_MODE = 0o700;
+export const SECURE_FILE_MODE = 0o600;
+export async function ensureSecureDir(dir) {
+    await mkdir(dir, { recursive: true, mode: SECURE_DIR_MODE });
+    await chmodIfPresent(dir, SECURE_DIR_MODE);
+}
+export async function writeSecureFile(file, data, options = {}) {
+    await ensureSecureDir(path.dirname(file));
+    await writeFile(file, data, { ...options, mode: SECURE_FILE_MODE });
+    await chmodIfPresent(file, SECURE_FILE_MODE);
+}
+export async function appendSecureFile(file, data) {
+    await ensureSecureDir(path.dirname(file));
+    await writeFile(file, data, { flag: "a", mode: SECURE_FILE_MODE });
+    await chmodIfPresent(file, SECURE_FILE_MODE);
+}
+async function chmodIfPresent(target, mode) {
+    try {
+        await chmod(target, mode);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+            throw error;
+        }
+    }
+}