brainclaw 0.19.2

package/dist/core/contradictions.js

@@ -0,0 +1,270 @@
+const NEGATION_PAIRS = [
+    { positive: 'must', negative: 'must not', kind: 'negation_pair' },
+    { positive: 'must', negative: 'must never', kind: 'negation_pair' },
+    { positive: 'should', negative: 'should not', kind: 'negation_pair' },
+    { positive: 'should', negative: 'should never', kind: 'negation_pair' },
+    { positive: 'always', negative: 'never', kind: 'negation_pair' },
+    { positive: 'enable', negative: 'disable', kind: 'toggle_pair' },
+    { positive: 'enabled', negative: 'disabled', kind: 'toggle_pair' },
+    { positive: 'use', negative: 'do not use', kind: 'usage_pair' },
+    { positive: 'use', negative: 'avoid', kind: 'usage_pair' },
+    { positive: 'allow', negative: 'block', kind: 'policy_pair' },
+    { positive: 'allow', negative: 'deny', kind: 'policy_pair' },
+    { positive: 'required', negative: 'forbidden', kind: 'policy_pair' },
+];
+const STOP_WORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'are',
+    'be',
+    'by',
+    'for',
+    'from',
+    'in',
+    'is',
+    'it',
+    'of',
+    'on',
+    'or',
+    'the',
+    'to',
+    'with',
+    'must',
+    'must not',
+    'must never',
+    'should',
+    'should not',
+    'should never',
+    'always',
+    'never',
+    'enable',
+    'disable',
+    'enabled',
+    'disabled',
+    'use',
+    'do not use',
+    'avoid',
+    'allow',
+    'block',
+    'deny',
+    'required',
+    'forbidden',
+]);
+export function detectContradictions(state) {
+    const reports = [];
+    const constraints = state.active_constraints.filter((constraint) => constraint.status === 'active');
+    const decisions = state.recent_decisions;
+    comparePairs(constraints, 'constraints', reports);
+    comparePairs(decisions, 'decisions', reports);
+    compareCrossSection(constraints, decisions, reports);
+    return sortContradictions(reports);
+}
+export function detectNewItemContradictions(newText, newTags, newPaths, state, newProjectId) {
+    const reports = [];
+    const candidate = {
+        id: 'new_item',
+        text: newText,
+        tags: newTags,
+        related_paths: newPaths,
+        project_id: newProjectId,
+    };
+    const check = (existing, section) => {
+        const signal = detectComparableContradiction(candidate, existing);
+        if (!signal) {
+            return;
+        }
+        reports.push({
+            item_id: candidate.id,
+            conflicts_with: existing.id,
+            reason: signal.reason,
+            section,
+            score: signal.score,
+            severity: classifySeverity(signal.score),
+            kind: signal.kind,
+        });
+    };
+    for (const constraint of state.active_constraints.filter((item) => item.status === 'active')) {
+        check(constraint, 'constraints');
+    }
+    for (const decision of state.recent_decisions) {
+        check(decision, 'decisions');
+    }
+    return sortContradictions(reports);
+}
+export function summarizeContradictions(reports, maxItems = 2) {
+    if (reports.length === 0) {
+        return undefined;
+    }
+    const parts = reports.slice(0, maxItems).map((report) => `[${report.conflicts_with}] ${report.reason}`);
+    const suffix = reports.length > maxItems ? ` (+${reports.length - maxItems} more)` : '';
+    return `${reports.length} contradiction(s): ${parts.join('; ')}${suffix}`;
+}
+export function hasBlockingContradictions(reports) {
+    return reports.some((report) => report.severity === 'medium' || report.severity === 'high');
+}
+function comparePairs(items, section, reports) {
+    for (let index = 0; index < items.length; index++) {
+        for (let offset = index + 1; offset < items.length; offset++) {
+            const left = items[index];
+            const right = items[offset];
+            const signal = detectComparableContradiction(left, right);
+            if (!signal) {
+                continue;
+            }
+            reports.push({
+                item_id: left.id,
+                conflicts_with: right.id,
+                reason: signal.reason,
+                section,
+                score: signal.score,
+                severity: classifySeverity(signal.score),
+                kind: signal.kind,
+            });
+        }
+    }
+}
+function compareCrossSection(constraints, decisions, reports) {
+    for (const constraint of constraints) {
+        for (const decision of decisions) {
+            const signal = detectComparableContradiction(constraint, decision);
+            if (!signal) {
+                continue;
+            }
+            reports.push({
+                item_id: constraint.id,
+                conflicts_with: decision.id,
+                reason: signal.reason,
+                section: 'constraints_vs_decisions',
+                score: signal.score,
+                severity: classifySeverity(signal.score),
+                kind: signal.kind,
+            });
+        }
+    }
+}
+function detectComparableContradiction(left, right) {
+    const domain = scoreDomainOverlap(left, right);
+    if (domain <= 0) {
+        return undefined;
+    }
+    const lexical = detectLexicalConflict(left.text, right.text);
+    if (!lexical) {
+        return undefined;
+    }
+    return {
+        kind: lexical.kind,
+        reason: lexical.reason,
+        score: lexical.score + domain,
+    };
+}
+function detectLexicalConflict(leftText, rightText) {
+    const normalizedLeft = normalize(leftText);
+    const normalizedRight = normalize(rightText);
+    const tokensLeft = tokenSet(normalizedLeft);
+    const tokensRight = tokenSet(normalizedRight);
+    const shared = sharedTokens(tokensLeft, tokensRight);
+    const jaccard = jaccardIndex(tokensLeft, tokensRight);
+    for (const pair of NEGATION_PAIRS) {
+        const leftHasPositive = normalizedLeft.includes(pair.positive);
+        const leftHasNegative = normalizedLeft.includes(pair.negative);
+        const rightHasPositive = normalizedRight.includes(pair.positive);
+        const rightHasNegative = normalizedRight.includes(pair.negative);
+        if (!((leftHasPositive && rightHasNegative) || (leftHasNegative && rightHasPositive))) {
+            continue;
+        }
+        if (shared.length === 0 && jaccard < 0.15) {
+            return undefined;
+        }
+        const overlapBoost = Math.min(shared.length, 3);
+        const score = 5 + overlapBoost + Math.round(jaccard * 4);
+        const overlapSummary = shared.slice(0, 3).join(', ');
+        const overlapText = overlapSummary ? ` around ${overlapSummary}` : '';
+        return {
+            kind: pair.kind,
+            reason: `"${pair.positive}" vs "${pair.negative}"${overlapText}`,
+            score,
+        };
+    }
+    return undefined;
+}
+function normalize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s/_-]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function tokenSet(normalized) {
+    const tokens = normalized
+        .split(/[^a-z0-9]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 2 && !STOP_WORDS.has(token));
+    return new Set(tokens);
+}
+function sharedTokens(left, right) {
+    const result = [];
+    for (const token of left) {
+        if (right.has(token)) {
+            result.push(token);
+        }
+    }
+    return result.sort();
+}
+function jaccardIndex(left, right) {
+    if (left.size === 0 || right.size === 0) {
+        return 0;
+    }
+    const intersection = sharedTokens(left, right).length;
+    const union = new Set([...left, ...right]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+function scoreDomainOverlap(left, right) {
+    let score = 0;
+    if (pathsOverlap(left.related_paths, right.related_paths)) {
+        score += 3;
+    }
+    if (tagsOverlap(left.tags, right.tags)) {
+        score += 2;
+    }
+    if (left.project_id && right.project_id && left.project_id === right.project_id) {
+        score += 1;
+    }
+    return score;
+}
+function classifySeverity(score) {
+    if (score >= 10) {
+        return 'high';
+    }
+    if (score >= 7) {
+        return 'medium';
+    }
+    return 'low';
+}
+function pathsOverlap(left, right) {
+    if (!left || !right || left.length === 0 || right.length === 0) {
+        return false;
+    }
+    return left.some((leftPath) => right.some((rightPath) => leftPath.startsWith(rightPath) || rightPath.startsWith(leftPath) || leftPath === rightPath));
+}
+function tagsOverlap(left, right) {
+    return left.some((tag) => right.includes(tag));
+}
+function sortContradictions(reports) {
+    const severityRank = {
+        high: 3,
+        medium: 2,
+        low: 1,
+    };
+    return [...reports].sort((left, right) => {
+        const severityDelta = severityRank[right.severity] - severityRank[left.severity];
+        if (severityDelta !== 0) {
+            return severityDelta;
+        }
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.conflicts_with.localeCompare(right.conflicts_with);
+    });
+}
+//# sourceMappingURL=contradictions.js.map

package/dist/core/coordination.js

@@ -0,0 +1,86 @@
+import { findAgentIdentityByName, resolveAgentScope, resolveCurrentAgentIdentity } from './agent-registry.js';
+import { loadConfig } from './config.js';
+import { resolveCurrentHostId } from './host.js';
+import { listClaims } from './claims.js';
+import { inferProjectFromTarget, loadInstructions, resolveInstructions } from './instructions.js';
+import { buildReputationSummary, findAgentReputationSummary } from './reputation.js';
+import { listRuntimeNotes } from './runtime.js';
+import { loadState, saveState } from './state.js';
+export function buildCoordinationSnapshot(options = {}) {
+    const config = loadConfig(options.cwd);
+    const state = loadState(options.cwd);
+    const currentHost = resolveCurrentHostId();
+    const project = options.project ?? inferProjectFromTarget(options.target, config);
+    const agent = resolveAgentScope(options.agent, options.cwd);
+    const resolvedAgentIdentity = agent
+        ? (options.agent ? findAgentIdentityByName(agent, options.cwd) : resolveCurrentAgentIdentity(options.cwd))
+        : undefined;
+    const claims = listClaims(options.cwd).filter((claim) => claim.status === 'active');
+    const runtimeNotes = listRuntimeNotes({
+        agent,
+        hostId: options.host,
+        includeAllHosts: options.allHosts,
+    }, options.cwd);
+    const activePlans = state.plan_items.filter((plan) => plan.status !== 'done' && plan.status !== 'dropped');
+    const openHandoffs = state.open_handoffs.filter((handoff) => handoff.status === 'open');
+    const instructions = resolveInstructions(loadInstructions(options.cwd), { project, agent });
+    const reputationSummary = options.includeReputation ? buildReputationSummary(options.cwd) : undefined;
+    const agentReputation = options.includeReputation && agent
+        ? findAgentReputationSummary(resolvedAgentIdentity?.agent_id ?? agent, options.cwd)
+        : undefined;
+    const filteredPlans = project
+        ? activePlans.filter((plan) => !plan.project || plan.project === project)
+        : activePlans;
+    const filteredClaims = project
+        ? claims.filter((claim) => !claim.project || claim.project === project)
+        : claims;
+    // perf.3: filter session lifecycle notes unless explicitly requested
+    const sessionMetaNoteTypes = new Set(['session_start', 'session_end']);
+    const visibleNotes = options.includeSessionMeta
+        ? runtimeNotes
+        : runtimeNotes.filter((note) => !sessionMetaNoteTypes.has(note.note_type ?? ''));
+    const sessionMetaHidden = runtimeNotes.length - visibleNotes.length;
+    const filteredNotes = project
+        ? visibleNotes.filter((note) => !note.project || note.project === project)
+        : visibleNotes;
+    // factor out handoff filter for reuse in auto-acknowledge
+    const filteredHandoffs = agent
+        ? openHandoffs.filter((h) => (!project || !h.project || h.project === project) && (h.to === agent || h.from === agent))
+        : (project ? openHandoffs.filter((h) => !h.project || h.project === project) : openHandoffs);
+    // perf.2: auto-acknowledge shown handoffs
+    if (options.autoAcknowledge && filteredHandoffs.length > 0) {
+        const toAckIds = new Set(filteredHandoffs.map((h) => h.id));
+        let changed = false;
+        for (const h of state.open_handoffs) {
+            if (toAckIds.has(h.id) && h.status === 'open') {
+                h.status = 'accepted';
+                changed = true;
+            }
+        }
+        if (changed)
+            saveState(state, options.cwd);
+    }
+    return {
+        project_id: config.project_id,
+        current_host: currentHost,
+        host_filter: options.host,
+        all_hosts: options.allHosts ?? false,
+        project,
+        agent,
+        agent_id: resolvedAgentIdentity?.agent_id,
+        active_plans: filteredPlans.map((plan) => ({
+            ...plan,
+            claims: filteredClaims.filter((claim) => claim.plan_id === plan.id),
+        })),
+        active_claims: agent
+            ? filteredClaims.filter((claim) => claim.agent === agent)
+            : filteredClaims,
+        runtime_notes: filteredNotes,
+        session_meta_hidden: sessionMetaHidden,
+        open_handoffs: filteredHandoffs,
+        resolved_instructions: instructions,
+        reputation_summary: reputationSummary,
+        agent_reputation: agentReputation,
+    };
+}
+//# sourceMappingURL=coordination.js.map

package/dist/core/cross-project.js

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import { loadConfig } from './config.js';
+import { loadState } from './state.js';
+import { saveRuntimeNote } from './runtime.js';
+import { memoryExists } from './io.js';
+/**
+ * Resolves cross_project_links from config, converting relative paths to absolute.
+ */
+export function resolveCrossProjectLinks(cwd) {
+    const baseCwd = cwd ?? process.cwd();
+    let config;
+    try {
+        config = loadConfig(cwd);
+    }
+    catch {
+        return [];
+    }
+    return (config.cross_project_links ?? []).map((link) => {
+        const absolutePath = path.isAbsolute(link.path)
+            ? link.path
+            : path.resolve(baseCwd, link.path);
+        const available = memoryExists(absolutePath);
+        let projectName = link.name ?? path.basename(absolutePath);
+        if (available) {
+            try {
+                const linkedConfig = loadConfig(absolutePath);
+                projectName = link.name ?? linkedConfig.project_name ?? projectName;
+            }
+            catch { /* use basename fallback */ }
+        }
+        return { ...link, absolutePath, projectName, available };
+    });
+}
+/**
+ * Detects cycles in cross_project_links (A → B → A).
+ * Returns the paths involved in any cycle found.
+ */
+export function detectCrossProjectCycles(cwd) {
+    const baseCwd = path.resolve(cwd ?? process.cwd());
+    const cycles = [];
+    function walk(currentCwd, visited) {
+        let links = [];
+        try {
+            links = resolveCrossProjectLinks(currentCwd);
+        }
+        catch {
+            return;
+        }
+        for (const link of links) {
+            const normalized = path.resolve(link.absolutePath);
+            if (visited.includes(normalized)) {
+                cycles.push([...visited, normalized]);
+                return;
+            }
+            walk(normalized, [...visited, normalized]);
+        }
+    }
+    walk(baseCwd, [baseCwd]);
+    return cycles;
+}
+/**
+ * Loads state from a linked project (read-only).
+ */
+export function loadCrossProjectState(absolutePath) {
+    return loadState(absolutePath);
+}
+/**
+ * Writes a runtime note into a target (publisher-linked) project's runtime dir.
+ * Used by bclaw_write_note --cross-project.
+ */
+export function writeCrossProjectNote(targetAbsolutePath, note, sourceCwd) {
+    const links = resolveCrossProjectLinks(sourceCwd);
+    const link = links.find((l) => path.resolve(l.absolutePath) === path.resolve(targetAbsolutePath));
+    if (!link) {
+        throw new Error(`No cross_project_link configured for path: ${targetAbsolutePath}`);
+    }
+    if (link.role !== 'publisher') {
+        throw new Error(`Cross-project link to '${link.projectName}' is role=subscriber — cannot write notes. Set role: publisher to enable push.`);
+    }
+    if (!link.available) {
+        throw new Error(`Target project not found or not initialized: ${targetAbsolutePath}`);
+    }
+    saveRuntimeNote({ ...note, note_type: 'cross_project' }, targetAbsolutePath);
+}
+/**
+ * Returns the absolute path of a cross-project link by name or path fragment.
+ */
+export function resolveCrossProjectTarget(nameOrPath, cwd) {
+    const links = resolveCrossProjectLinks(cwd);
+    const match = links.find((l) => l.projectName === nameOrPath ||
+        l.path === nameOrPath ||
+        l.absolutePath === nameOrPath ||
+        path.basename(l.absolutePath) === nameOrPath);
+    if (!match) {
+        throw new Error(`No cross_project_link found matching: '${nameOrPath}'. Check your config.yaml cross_project_links.`);
+    }
+    return match;
+}
+//# sourceMappingURL=cross-project.js.map

package/dist/core/duplicates.js

@@ -0,0 +1,72 @@
+export function detectDuplicates(candidateText, candidateType, state, pendingCandidates) {
+    const matches = [];
+    const normalised = normalise(candidateText);
+    // Check state entries for the same type
+    const sectionMap = {
+        constraint: state.active_constraints,
+        decision: state.recent_decisions,
+        trap: state.known_traps,
+        handoff: state.open_handoffs.map(h => ({ ...h, text: h.text })),
+    };
+    const items = sectionMap[candidateType] ?? [];
+    for (const item of items) {
+        const sim = similarity(normalised, normalise(item.text));
+        if (sim >= 0.7) {
+            matches.push({
+                id: item.id,
+                source: 'state',
+                text: item.text,
+                reason: sim >= 0.95 ? 'exact match' : 'similar text',
+            });
+        }
+    }
+    // Check pending candidates of the same type
+    for (const c of pendingCandidates) {
+        if (c.type !== candidateType)
+            continue;
+        const sim = similarity(normalised, normalise(c.text));
+        if (sim >= 0.7) {
+            matches.push({
+                id: c.id,
+                source: 'candidate',
+                text: c.text,
+                reason: sim >= 0.95 ? 'exact match' : 'similar text',
+            });
+        }
+    }
+    return matches;
+}
+function normalise(text) {
+    return text.toLowerCase().replace(/[^a-z0-9\s]/g, '').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Bigram-based similarity (Dice coefficient). Fast, no dependencies.
+ */
+function similarity(a, b) {
+    if (a === b)
+        return 1;
+    if (a.length < 2 || b.length < 2)
+        return 0;
+    const bigramsA = bigrams(a);
+    const bigramsB = bigrams(b);
+    let intersection = 0;
+    const bCopy = new Map(bigramsB);
+    for (const [bg, count] of bigramsA) {
+        const bCount = bCopy.get(bg) ?? 0;
+        if (bCount > 0) {
+            intersection += Math.min(count, bCount);
+        }
+    }
+    const totalA = [...bigramsA.values()].reduce((s, v) => s + v, 0);
+    const totalB = [...bigramsB.values()].reduce((s, v) => s + v, 0);
+    return (2 * intersection) / (totalA + totalB);
+}
+function bigrams(text) {
+    const result = new Map();
+    for (let i = 0; i < text.length - 1; i++) {
+        const bg = text.slice(i, i + 2);
+        result.set(bg, (result.get(bg) ?? 0) + 1);
+    }
+    return result;
+}
+//# sourceMappingURL=duplicates.js.map

package/dist/core/event-log.js

@@ -0,0 +1,152 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryDir } from './io.js';
+import { nowISO } from './ids.js';
+import { logger } from './logger.js';
+const EVENT_LOG_FILE = 'events.jsonl';
+const CURSORS_DIR = '.cursors';
+// --- Writer ---
+export function appendEvent(event, cwd) {
+    try {
+        const full = {
+            ts: event.ts ?? nowISO(),
+            agent: event.agent ?? 'unknown',
+            agent_id: event.agent_id,
+            action: event.action,
+            item_type: event.item_type,
+            item_id: event.item_id,
+            summary: event.summary,
+        };
+        const line = JSON.stringify(Object.fromEntries(Object.entries(full).filter(([, v]) => v !== undefined)));
+        const logPath = eventLogPath(cwd);
+        fs.appendFileSync(logPath, line + '\n', 'utf-8');
+    }
+    catch (err) {
+        logger.debug('Failed to write event log entry:', err);
+    }
+}
+// --- Reader ---
+export function readAllEvents(cwd) {
+    const logPath = eventLogPath(cwd);
+    if (!fs.existsSync(logPath))
+        return [];
+    const lines = fs.readFileSync(logPath, 'utf-8').split('\n').filter(Boolean);
+    const events = [];
+    for (const line of lines) {
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return events;
+}
+function cursorsDir(cwd) {
+    return path.join(memoryDir(cwd), CURSORS_DIR);
+}
+function cursorPath(agent, cwd) {
+    return path.join(cursorsDir(cwd), `${agent}.json`);
+}
+function loadCursor(agent, cwd) {
+    const fp = cursorPath(agent, cwd);
+    if (!fs.existsSync(fp))
+        return { offset: 0, last_read: '' };
+    try {
+        return JSON.parse(fs.readFileSync(fp, 'utf-8'));
+    }
+    catch {
+        return { offset: 0, last_read: '' };
+    }
+}
+function saveCursor(agent, cursor, cwd) {
+    const dir = cursorsDir(cwd);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(cursorPath(agent, cwd), JSON.stringify(cursor), 'utf-8');
+}
+/**
+ * Read events unseen by this agent since their last read.
+ * Updates the cursor after reading.
+ */
+export function readUnseenEvents(agent, cwd) {
+    const logPath = eventLogPath(cwd);
+    if (!fs.existsSync(logPath))
+        return [];
+    const cursor = loadCursor(agent, cwd);
+    const stat = fs.statSync(logPath);
+    if (stat.size <= cursor.offset)
+        return [];
+    // Read from offset
+    const fd = fs.openSync(logPath, 'r');
+    const buffer = Buffer.alloc(stat.size - cursor.offset);
+    fs.readSync(fd, buffer, 0, buffer.length, cursor.offset);
+    fs.closeSync(fd);
+    const newContent = buffer.toString('utf-8');
+    const lines = newContent.split('\n').filter(Boolean);
+    const events = [];
+    for (const line of lines) {
+        try {
+            const evt = JSON.parse(line);
+            // Exclude events from self
+            if (evt.agent !== agent) {
+                events.push(evt);
+            }
+        }
+        catch {
+            // skip
+        }
+    }
+    // Update cursor
+    saveCursor(agent, { offset: stat.size, last_read: nowISO() }, cwd);
+    return events;
+}
+/**
+ * Build a compact notification summary from unseen events.
+ */
+export function buildNotificationSummary(events) {
+    if (events.length === 0)
+        return undefined;
+    const summary = {};
+    for (const evt of events) {
+        const key = `${evt.action}:${evt.item_type}`;
+        summary[key] = (summary[key] ?? 0) + 1;
+    }
+    return summary;
+}
+// --- Rotation ---
+const MAX_EVENT_LOG_BYTES = 10 * 1024 * 1024; // 10MB
+/**
+ * Check if the event log needs rotation. Returns true if rotated.
+ */
+export function rotateEventLogIfNeeded(cwd) {
+    const logPath = eventLogPath(cwd);
+    if (!fs.existsSync(logPath))
+        return false;
+    const stat = fs.statSync(logPath);
+    if (stat.size < MAX_EVENT_LOG_BYTES)
+        return false;
+    try {
+        const archiveName = `events.${Date.now()}.jsonl`;
+        const archivePath = path.join(memoryDir(cwd), archiveName);
+        fs.renameSync(logPath, archivePath);
+        // Reset all cursors
+        const dir = cursorsDir(cwd);
+        if (fs.existsSync(dir)) {
+            for (const file of fs.readdirSync(dir).filter(f => f.endsWith('.json'))) {
+                fs.unlinkSync(path.join(dir, file));
+            }
+        }
+        return true;
+    }
+    catch (err) {
+        logger.debug('Failed to rotate event log:', err);
+        return false;
+    }
+}
+// --- Helpers ---
+function eventLogPath(cwd) {
+    return path.join(memoryDir(cwd), EVENT_LOG_FILE);
+}
+//# sourceMappingURL=event-log.js.map