brainclaw 0.29.2 → 1.5.3

package/dist/core/loops/lock.js

@@ -0,0 +1,385 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { memoryDir } from '../io.js';
+import { nowISO } from '../ids.js';
+/**
+ * Per-loop exclusive lock + idempotency + fencing helpers.
+ *
+ * Implements the commit protocol from docs/concepts/loop-engine.md §Persistence.
+ * For synchronous MVP mutations, the lock window is short (< 100ms typically) so
+ * lease renewal via an internal heartbeat is not yet wired up; the hard_deadline
+ * is still recorded in the lock blob and used by the stale-lock recovery rules.
+ */
+export const LOCK_BACKOFF_BASE_MS = 10;
+export const LOCK_BACKOFF_TOTAL_MS = 500;
+export const LEASE_WINDOW_MS = 60_000;
+export const LEASE_RENEWAL_INTERVAL_MS = 30_000;
+export const LEASE_GRACE_MS = 30_000;
+export const DEFAULT_MAX_MUTATION_DURATION_MS = {
+    open: 30_000,
+    turn: 30_000,
+    advance: 30_000,
+    pause: 30_000,
+    resume: 30_000,
+    close: 30_000,
+    add_artifact: 60_000,
+    complete_turn: 60_000,
+};
+export const IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1000;
+export class LockTimeoutError extends Error {
+    lockPath;
+    constructor(lockPath) {
+        super(`lock_timeout at ${lockPath}`);
+        this.lockPath = lockPath;
+        this.name = 'LockTimeoutError';
+    }
+}
+export class LockLostError extends Error {
+    lockPath;
+    expected;
+    actual;
+    constructor(lockPath, expected, actual) {
+        super(`lock_lost: expected mutation_id=${expected}, found=${actual ?? 'missing'} at ${lockPath}`);
+        this.lockPath = lockPath;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'LockLostError';
+    }
+}
+export class VersionConflictError extends Error {
+    loopId;
+    expected;
+    actual;
+    constructor(loopId, expected, actual) {
+        super(`version_conflict on ${loopId}: expected ${expected}, actual ${actual}`);
+        this.loopId = loopId;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'VersionConflictError';
+    }
+}
+export class IdempotencyKeyReusedError extends Error {
+    storedHash;
+    submittedHash;
+    constructor(storedHash, submittedHash) {
+        super('idempotency_key_reused_with_different_body');
+        this.storedHash = storedHash;
+        this.submittedHash = submittedHash;
+        this.name = 'IdempotencyKeyReusedError';
+    }
+}
+export class IdempotencyOwnerMismatchError extends Error {
+    storedOwner;
+    submittedOwner;
+    constructor(storedOwner, submittedOwner) {
+        super('idempotency_owner_mismatch');
+        this.storedOwner = storedOwner;
+        this.submittedOwner = submittedOwner;
+        this.name = 'IdempotencyOwnerMismatchError';
+    }
+}
+/* ============================ path resolution ============================= */
+function loopsRoot(cwd) {
+    return path.join(memoryDir(cwd ?? process.cwd()), 'loops');
+}
+function locksDir(cwd) {
+    return path.join(loopsRoot(cwd), 'locks');
+}
+function openLocksDir(cwd) {
+    return path.join(locksDir(cwd), 'open');
+}
+function idempotencyDir(loopId, cwd) {
+    return path.join(loopsRoot(cwd), 'idempotency', loopId);
+}
+function idempotencyOpenDir(agentId, cwd) {
+    return path.join(loopsRoot(cwd), 'idempotency-open', agentId);
+}
+function conflictsDir(cwd) {
+    return path.join(loopsRoot(cwd), 'conflicts');
+}
+function loopLockPath(loopId, cwd) {
+    return path.join(locksDir(cwd), `${loopId}.lock`);
+}
+function openLockPath(agentId, clientRequestId, cwd) {
+    return path.join(openLocksDir(cwd), agentId, `${clientRequestId}.lock`);
+}
+function ensureDirFor(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+/* ============================== JSON helpers ============================= */
+function readJsonIfExists(filePath) {
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeJsonAtomic(filePath, data) {
+    ensureDirFor(filePath);
+    const tmp = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    fs.renameSync(tmp, filePath);
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalizeJson(item));
+    }
+    if (value && typeof value === 'object') {
+        const record = value;
+        const canonical = {};
+        for (const key of Object.keys(record).sort()) {
+            canonical[key] = canonicalizeJson(record[key]);
+        }
+        return canonical;
+    }
+    return value;
+}
+export function hashRequest(payload) {
+    const canonical = JSON.stringify(canonicalizeJson(payload));
+    return crypto.createHash('sha256').update(canonical).digest('hex');
+}
+function loadIdempotencyRecord(kind, key, cwd) {
+    let filePath;
+    if (kind === 'loop') {
+        if (!key.loopId)
+            throw new Error('loadIdempotencyRecord: loopId required for loop kind');
+        filePath = path.join(idempotencyDir(key.loopId, cwd), `${key.clientRequestId}.json`);
+    }
+    else {
+        if (!key.agentId)
+            throw new Error('loadIdempotencyRecord: agentId required for open kind');
+        filePath = path.join(idempotencyOpenDir(key.agentId, cwd), `${key.clientRequestId}.json`);
+    }
+    const record = readJsonIfExists(filePath);
+    if (record && Date.parse(record.stored_at) + IDEMPOTENCY_TTL_MS < Date.now()) {
+        return { path: filePath, record: undefined };
+    }
+    return { path: filePath, record };
+}
+/* =============================== lock I/O ================================ */
+function readLockBlob(lockPath) {
+    return readJsonIfExists(lockPath) ?? null;
+}
+function writeLockAtomic(lockPath, blob) {
+    writeJsonAtomic(lockPath, blob);
+}
+function processIsAlive(pid) {
+    try {
+        // Signal 0 just checks for the process's existence without actually sending a signal.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        return code === 'EPERM';
+    }
+}
+function lockIsStale(blob, now) {
+    if (now > Date.parse(blob.hard_deadline))
+        return true;
+    if (blob.host_id === os.hostname() && !processIsAlive(blob.pid))
+        return true;
+    if (now > Date.parse(blob.lease_until) + LEASE_GRACE_MS)
+        return true;
+    return false;
+}
+function acquireRaw(lockPath, blob) {
+    ensureDirFor(lockPath);
+    const tmp = path.join(path.dirname(lockPath), `.${path.basename(lockPath)}.${process.pid}.${Date.now()}.${crypto.randomBytes(3).toString('hex')}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(blob, null, 2));
+    try {
+        // fs.renameSync is atomic on POSIX but will overwrite on Windows. We want exclusive:
+        // use link(tmp, lockPath) + unlink(tmp) which is atomic + fails on EEXIST.
+        fs.linkSync(tmp, lockPath);
+        fs.unlinkSync(tmp);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* ignore */
+        }
+        if (code === 'EEXIST')
+            return false;
+        throw err;
+    }
+}
+export function acquireLock(options) {
+    const durationMs = options.maxMutationDurationMs ?? DEFAULT_MAX_MUTATION_DURATION_MS[options.intent] ?? 30_000;
+    const timeoutMs = options.timeoutMs ?? LOCK_BACKOFF_TOTAL_MS;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const existing = readLockBlob(options.lockPath);
+        if (existing) {
+            if (lockIsStale(existing, Date.now())) {
+                try {
+                    fs.unlinkSync(options.lockPath);
+                }
+                catch {
+                    /* race with another reaper; retry */
+                }
+            }
+        }
+        const nowIso = nowISO();
+        const nowMs = Date.now();
+        const blob = {
+            pid: process.pid,
+            host_id: os.hostname(),
+            agent_id: options.agentId,
+            acquired_at: nowIso,
+            lease_until: new Date(nowMs + LEASE_WINDOW_MS).toISOString(),
+            hard_deadline: new Date(nowMs + durationMs).toISOString(),
+            mutation_id: crypto.randomUUID().replace(/-/g, ''),
+        };
+        if (acquireRaw(options.lockPath, blob)) {
+            const lockPath = options.lockPath;
+            return {
+                path: lockPath,
+                blob,
+                release() {
+                    try {
+                        const current = readLockBlob(lockPath);
+                        if (current && current.mutation_id === blob.mutation_id) {
+                            fs.unlinkSync(lockPath);
+                        }
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                },
+                fenceCheck() {
+                    const current = readLockBlob(lockPath);
+                    if (!current || current.mutation_id !== blob.mutation_id) {
+                        throw new LockLostError(lockPath, blob.mutation_id, current?.mutation_id ?? null);
+                    }
+                },
+            };
+        }
+        // Jittered backoff.
+        const base = Math.min(LOCK_BACKOFF_BASE_MS * 2, 80);
+        const jitter = crypto.randomInt(0, base);
+        const sleepMs = Math.min(deadline - Date.now(), base + jitter);
+        if (sleepMs <= 0)
+            break;
+        sleepSync(sleepMs);
+    }
+    throw new LockTimeoutError(options.lockPath);
+}
+function sleepSync(ms) {
+    const end = Date.now() + ms;
+    // Tight but cheap busy wait for short backoffs.
+    while (Date.now() < end) {
+        // Yield via SharedArrayBuffer wait if available; otherwise busy-loop.
+        try {
+            const sab = new SharedArrayBuffer(4);
+            const view = new Int32Array(sab);
+            Atomics.wait(view, 0, 0, end - Date.now());
+            break;
+        }
+        catch {
+            /* fallback */
+        }
+    }
+}
+export function withLoopLock(options) {
+    const lockPath = options.scope.kind === 'loop'
+        ? loopLockPath(options.scope.loopId, options.cwd)
+        : openLockPath(options.agentId, options.scope.clientRequestId, options.cwd);
+    const acquired = acquireLock({
+        lockPath,
+        agentId: options.agentId,
+        intent: options.intent,
+    });
+    try {
+        // Idempotency short-circuit (inside lock).
+        if (options.clientRequestId && options.requestPayload !== undefined) {
+            const loopIdForKey = options.scope.kind === 'loop'
+                ? options.scope.loopId
+                : options.loopIdForIdempotency;
+            const { path: idPath, record } = loadIdempotencyRecord(loopIdForKey ? 'loop' : 'open', loopIdForKey
+                ? { loopId: loopIdForKey, clientRequestId: options.clientRequestId }
+                : { agentId: options.agentId, clientRequestId: options.clientRequestId }, options.cwd);
+            const submittedHash = hashRequest(options.requestPayload);
+            if (record) {
+                if (record.request_hash !== submittedHash) {
+                    throw new IdempotencyKeyReusedError(record.request_hash, submittedHash);
+                }
+                if (options.requireCallerMatch && record.owner_agent_id !== options.agentId) {
+                    throw new IdempotencyOwnerMismatchError(record.owner_agent_id, options.agentId);
+                }
+                return record.response;
+            }
+            // CAS check (after idempotency short-circuit).
+            if (options.expectedVersion !== undefined && options.currentVersion) {
+                const actual = options.currentVersion();
+                if (actual !== options.expectedVersion) {
+                    recordConflict({
+                        loopId: loopIdForKey ?? 'unknown',
+                        attemptedBy: options.agentId,
+                        expectedVersion: options.expectedVersion,
+                        actualVersion: actual,
+                        rejectedIntent: options.intent,
+                        clientRequestId: options.clientRequestId,
+                        cwd: options.cwd,
+                    });
+                    throw new VersionConflictError(loopIdForKey ?? 'unknown', options.expectedVersion, actual);
+                }
+            }
+            const result = options.work({ fenceCheck: acquired.fenceCheck, mutationId: acquired.blob.mutation_id });
+            const storeRecord = {
+                response: result,
+                request_hash: submittedHash,
+                stored_at: nowISO(),
+                owner_agent_id: options.agentId,
+            };
+            writeJsonAtomic(idPath, storeRecord);
+            return result;
+        }
+        // No idempotency key — still honor CAS if supplied.
+        if (options.expectedVersion !== undefined && options.currentVersion && options.scope.kind === 'loop') {
+            const actual = options.currentVersion();
+            if (actual !== options.expectedVersion) {
+                recordConflict({
+                    loopId: options.scope.loopId,
+                    attemptedBy: options.agentId,
+                    expectedVersion: options.expectedVersion,
+                    actualVersion: actual,
+                    rejectedIntent: options.intent,
+                    clientRequestId: options.clientRequestId,
+                    cwd: options.cwd,
+                });
+                throw new VersionConflictError(options.scope.loopId, options.expectedVersion, actual);
+            }
+        }
+        return options.work({ fenceCheck: acquired.fenceCheck, mutationId: acquired.blob.mutation_id });
+    }
+    finally {
+        acquired.release();
+    }
+}
+export function recordConflict(input) {
+    const filePath = path.join(conflictsDir(input.cwd), `${input.loopId}.jsonl`);
+    ensureDirFor(filePath);
+    const entry = {
+        conflict_id: crypto.randomUUID(),
+        loop_id: input.loopId,
+        at: nowISO(),
+        attempted_by: input.attemptedBy,
+        expected_version: input.expectedVersion,
+        actual_version: input.actualVersion,
+        rejected_intent: input.rejectedIntent,
+        client_request_id: input.clientRequestId,
+    };
+    fs.appendFileSync(filePath, `${JSON.stringify(entry)}\n`);
+}
+//# sourceMappingURL=lock.js.map

package/dist/core/loops/store.js

@@ -0,0 +1,201 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryDir, writeFileAtomic } from '../io.js';
+import { nowISO } from '../ids.js';
+import { DEFAULT_PROTOCOLS, LoopEventSchema, LoopThreadSchema, } from './types.js';
+function loopsDir(cwd) {
+    return path.join(memoryDir(cwd ?? process.cwd()), 'loops');
+}
+function threadsDir(cwd) {
+    return path.join(loopsDir(cwd), 'threads');
+}
+function eventsDir(cwd) {
+    return path.join(loopsDir(cwd), 'events');
+}
+export function ensureLoopsDir(cwd) {
+    const dirs = [loopsDir(cwd), threadsDir(cwd), eventsDir(cwd)];
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+    }
+}
+function threadPath(id, cwd) {
+    return path.join(threadsDir(cwd), `${id}.json`);
+}
+function eventsPath(id, cwd) {
+    return path.join(eventsDir(cwd), `${id}.jsonl`);
+}
+function writeAtomic(filePath, contents) {
+    writeFileAtomic(filePath, contents);
+}
+function randomIdSegment() {
+    return crypto.randomBytes(8).toString('hex');
+}
+export function generateLoopId() {
+    return `lop_${randomIdSegment()}`;
+}
+export function generateSlotId() {
+    return `lsl_${randomIdSegment()}`;
+}
+export function generateMutationId() {
+    return crypto.randomUUID().replace(/-/g, '');
+}
+function resolveProtocol(kind, mode) {
+    // pln#492 phase 2.b — carry the iteration block from DEFAULT_PROTOCOLS
+    // into the thread's protocol so advance() / iteration-engine see it.
+    const iteration = DEFAULT_PROTOCOLS[kind].iteration;
+    if (kind === 'review') {
+        return { review_mode: mode ?? 'asymmetric' };
+    }
+    if (mode !== undefined) {
+        // mode is only meaningful for review loops today; ignore otherwise.
+        return iteration ? { iteration } : undefined;
+    }
+    return iteration ? { iteration } : undefined;
+}
+function buildSlot(partial) {
+    return {
+        slot_id: partial.slot_id ?? generateSlotId(),
+        role: partial.role,
+        agent: partial.agent,
+        agent_id: partial.agent_id,
+        assignment_id: partial.assignment_id,
+        claim_id: partial.claim_id,
+        phase: partial.phase,
+        status: partial.status ?? 'open',
+    };
+}
+export function appendEvent(loopId, event, cwd) {
+    const parsed = LoopEventSchema.parse(event);
+    ensureLoopsDir(cwd);
+    fs.appendFileSync(eventsPath(loopId, cwd), `${JSON.stringify(parsed)}\n`);
+}
+export function writeThreadFile(thread, cwd) {
+    const parsed = LoopThreadSchema.parse(thread);
+    ensureLoopsDir(cwd);
+    writeAtomic(threadPath(parsed.id, cwd), `${JSON.stringify(parsed, null, 2)}\n`);
+}
+export function openLoop(input, cwd) {
+    const protocolDefaults = DEFAULT_PROTOCOLS[input.kind];
+    const phases = input.phases ?? protocolDefaults.phases;
+    if (phases.length === 0) {
+        throw new Error('openLoop: phases must be non-empty');
+    }
+    const phaseNames = new Set(phases.map((p) => p.name));
+    if (phaseNames.size !== phases.length) {
+        throw new Error('openLoop: phase names must be unique');
+    }
+    const now = nowISO();
+    const id = generateLoopId();
+    const mutation_id = generateMutationId();
+    const slots = (input.slots ?? []).map(buildSlot);
+    const protocol = resolveProtocol(input.kind, input.mode);
+    const thread = {
+        schema_version: 1,
+        id,
+        version: 1,
+        mutation_id,
+        kind: input.kind,
+        title: input.title,
+        goal: input.goal,
+        protocol,
+        status: 'open',
+        phases,
+        current_phase: phases[0].name,
+        iteration_count: 0,
+        slots,
+        artifacts: [],
+        linked: input.linked,
+        stop_condition: input.stop_condition ?? protocolDefaults.stop_condition,
+        created_at: now,
+        updated_at: now,
+        created_by: input.created_by,
+    };
+    appendEvent(id, {
+        event_id: crypto.randomUUID(),
+        loop_id: id,
+        seq: 1,
+        at: now,
+        by: input.created_by,
+        mutation_id,
+        kind: 'opened',
+        initial_phase: thread.current_phase,
+        created_by: input.created_by,
+    }, cwd);
+    writeThreadFile(thread, cwd);
+    return thread;
+}
+export function getLoop(id, cwd) {
+    const filePath = threadPath(id, cwd);
+    if (!fs.existsSync(filePath))
+        return undefined;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return LoopThreadSchema.parse(JSON.parse(raw));
+}
+export function listLoops(filters = {}, cwd) {
+    const dir = threadsDir(cwd);
+    if (!fs.existsSync(dir))
+        return [];
+    const loops = [];
+    for (const file of fs.readdirSync(dir)) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const raw = fs.readFileSync(path.join(dir, file), 'utf8');
+            const loop = LoopThreadSchema.parse(JSON.parse(raw));
+            if (filters.kind && loop.kind !== filters.kind)
+                continue;
+            if (filters.status && loop.status !== filters.status)
+                continue;
+            loops.push(loop);
+        }
+        catch {
+            // Skip malformed files; the CAS/replay layer will surface diagnostics.
+        }
+    }
+    return loops.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+export function listLoopEvents(id, cwd) {
+    const filePath = eventsPath(id, cwd);
+    if (!fs.existsSync(filePath))
+        return [];
+    const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+    return lines.map((line) => LoopEventSchema.parse(JSON.parse(line)));
+}
+export function closeLoop(input, cwd) {
+    const current = getLoop(input.id, cwd);
+    if (!current) {
+        throw new Error(`closeLoop: unknown loop_id ${input.id}`);
+    }
+    if (current.status !== 'open' && current.status !== 'paused') {
+        throw new Error(`closeLoop: loop ${input.id} is already ${current.status}`);
+    }
+    const now = nowISO();
+    const mutation_id = generateMutationId();
+    const version = current.version + 1;
+    const events = listLoopEvents(input.id, cwd);
+    const seq = (events[events.length - 1]?.seq ?? 0) + 1;
+    const next = {
+        ...current,
+        version,
+        mutation_id,
+        status: input.final_status,
+        updated_at: now,
+        closed_at: now,
+    };
+    appendEvent(input.id, {
+        event_id: crypto.randomUUID(),
+        loop_id: input.id,
+        seq,
+        at: now,
+        by: input.actor,
+        mutation_id,
+        kind: 'closed',
+        final_status: input.final_status,
+        reason: input.reason,
+    }, cwd);
+    writeThreadFile(next, cwd);
+    return next;
+}
+//# sourceMappingURL=store.js.map