brainclaw 0.29.2 → 1.5.3

package/dist/core/assignments.js

@@ -0,0 +1,367 @@
+import fs from 'node:fs';
+import { AssignmentSchema } from './schema.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
+import { nowISO, generateIdWithLabel } from './ids.js';
+import { JsonStore } from './json-store.js';
+import { appendAuditEntry } from './audit.js';
+import { appendEvent } from './event-log.js';
+import { createRuntimeEvent } from './events.js';
+import { findLatestAgentRunForAssignment, recordAgentRunProgress, syncAgentRunFromAssignmentTransition } from './agentruns.js';
+// ── Directory / Store ────────────────────────────────────────
+function assignmentsDir(cwd, mode = 'read') {
+    return resolveEntityDir('assignments', cwd, mode);
+}
+function ensureAssignmentsDir(cwd) {
+    const dir = assignmentsDir(cwd, 'write');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+function assignmentStore(cwd) {
+    return new JsonStore({
+        dirPath: assignmentsDir(cwd, 'read'),
+        documentType: 'assignment',
+        getId: (a) => a.id,
+        sort: (a, b) => a.created_at.localeCompare(b.created_at),
+    });
+}
+// ── CRUD ─────────────────────────────────────────────────────
+export function saveAssignment(assignment, cwd) {
+    mutate({ cwd }, () => {
+        ensureAssignmentsDir(cwd);
+        const store = new JsonStore({
+            dirPath: assignmentsDir(cwd, 'write'),
+            documentType: 'assignment',
+            getId: (a) => a.id,
+            sort: (a, b) => a.created_at.localeCompare(b.created_at),
+        });
+        store.save(AssignmentSchema.parse(assignment));
+    });
+}
+export function loadAssignment(id, cwd) {
+    // JsonStore.load throws when the id is missing; honor the declared
+    // "| undefined" return type so callers (e.g. transitionAssignment)
+    // can emit their own 'Assignment not found' error with the right wording.
+    try {
+        return assignmentStore(cwd).load(id);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function listAssignments(cwd, filter) {
+    let items = assignmentStore(cwd).list();
+    if (filter?.status)
+        items = items.filter((a) => a.status === filter.status);
+    if (filter?.agent)
+        items = items.filter((a) => a.agent === filter.agent);
+    if (filter?.claim_id)
+        items = items.filter((a) => a.claim_id === filter.claim_id);
+    if (filter?.plan_id)
+        items = items.filter((a) => a.plan_id === filter.plan_id);
+    if (filter?.sequence_id)
+        items = items.filter((a) => a.sequence_id === filter.sequence_id);
+    return items;
+}
+// ── ID Generation ────────────────────────────────────────────
+export function generateAssignmentId(cwd) {
+    return generateIdWithLabel('assignments', cwd);
+}
+// ── Status FSM ───────────────────────────────────────────────
+/** Valid transitions: from → Set<to>.
+ *
+ * `rerouted` is reachable from every non-terminal state (pln#451 / trp#61):
+ * rerouting a claim must close the predecessor assignment regardless of where
+ * it was in the FSM. Previously only `blocked` could reach `rerouted`, which
+ * left assignments stuck in `created` or `offered` when the coordinator
+ * rerouted a still-unstarted lane.
+ */
+const VALID_TRANSITIONS = new Map([
+    ['created', new Set(['offered', 'rerouted'])],
+    ['offered', new Set(['accepted', 'failed', 'expired', 'rerouted'])],
+    ['accepted', new Set(['started', 'timed_out', 'rerouted'])],
+    ['started', new Set(['completed', 'failed', 'blocked', 'timed_out', 'rerouted'])],
+    ['failed', new Set(['retrying', 'rerouted'])],
+    ['timed_out', new Set(['retrying', 'rerouted'])],
+    ['retrying', new Set(['offered', 'rerouted'])],
+    ['blocked', new Set(['rerouted', 'started', 'failed'])],
+    // Terminal: completed, expired, rerouted (no outgoing transitions)
+]);
+export function validateTransition(from, to) {
+    const allowed = VALID_TRANSITIONS.get(from);
+    if (!allowed || !allowed.has(to)) {
+        return { valid: false, reason: `Invalid transition: ${from} → ${to}` };
+    }
+    return { valid: true };
+}
+/**
+ * Transition an assignment to a new status with FSM validation.
+ * Same-status transitions are idempotent no-ops (returns current state
+ * with idempotent=true instead of throwing). This handles network retries
+ * where a worker calls accepted/started again after a timeout.
+ * Updates relevant timestamps, emits event and audit entry.
+ */
+export function transitionAssignment(id, newStatus, options, cwd) {
+    const assignment = loadAssignment(id, cwd);
+    if (!assignment) {
+        throw new Error(`Assignment not found: ${id}`);
+    }
+    // Idempotent: same-status transition is a no-op (handles network retries)
+    if (assignment.status === newStatus) {
+        // Still update heartbeat for liveness tracking
+        assignment.last_heartbeat_at = nowISO();
+        assignment.updated_at = assignment.last_heartbeat_at;
+        saveAssignment(assignment, cwd);
+        return { assignment, previous_status: newStatus, idempotent: true };
+    }
+    const validation = validateTransition(assignment.status, newStatus);
+    if (!validation.valid) {
+        throw new Error(validation.reason);
+    }
+    const previous_status = assignment.status;
+    const now = nowISO();
+    // Update status
+    assignment.status = newStatus;
+    assignment.updated_at = now;
+    assignment.last_heartbeat_at = now;
+    if (options.status_reason)
+        assignment.status_reason = options.status_reason;
+    if (options.session_id)
+        assignment.session_id = options.session_id;
+    if (options.error_message)
+        assignment.error_message = options.error_message;
+    if (options.artifacts?.length) {
+        assignment.artifacts = [...assignment.artifacts, ...options.artifacts];
+    }
+    // Set transition-specific timestamps
+    switch (newStatus) {
+        case 'offered':
+            assignment.offered_at = now;
+            break;
+        case 'accepted':
+            assignment.accepted_at = now;
+            break;
+        case 'started':
+            assignment.started_at = now;
+            break;
+        case 'completed':
+            assignment.completed_at = now;
+            break;
+        case 'failed':
+            assignment.failed_at = now;
+            break;
+        case 'blocked':
+            assignment.blocked_at = now;
+            break;
+        case 'timed_out':
+            assignment.timed_out_at = now;
+            break;
+        case 'expired':
+            assignment.expired_at = now;
+            break;
+        case 'rerouted':
+            assignment.rerouted_at = now;
+            break;
+    }
+    saveAssignment(assignment, cwd);
+    emitAssignmentEvent(assignment, `assignment_${newStatus}`, options.actor, cwd);
+    if (options.syncAgentRun !== false) {
+        try {
+            syncAgentRunFromAssignmentTransition(assignment, newStatus, {
+                actor: options.actor,
+                actor_id: options.actor_id,
+                session_id: options.session_id,
+                status_reason: options.status_reason,
+                artifacts: options.artifacts,
+                error_message: options.error_message,
+            }, cwd);
+        }
+        catch {
+            /* best-effort: run state should not break assignment lifecycle */
+        }
+    }
+    appendAuditEntry({
+        actor: options.actor ?? assignment.agent,
+        actor_id: options.actor_id,
+        action: 'update',
+        item_id: assignment.id,
+        item_type: 'assignment',
+        before: { status: previous_status },
+        after: { status: newStatus, reason: options.status_reason },
+        scope: assignment.scope,
+        session_id: options.session_id,
+    }, cwd);
+    return { assignment, previous_status };
+}
+/**
+ * Record progress on a started assignment (heartbeat).
+ * Updates last_heartbeat_at without changing status.
+ */
+export function recordProgress(id, options, cwd) {
+    const assignment = loadAssignment(id, cwd);
+    if (!assignment) {
+        throw new Error(`Assignment not found: ${id}`);
+    }
+    if (assignment.status !== 'started') {
+        throw new Error(`Cannot record progress: assignment ${id} is ${assignment.status}, expected started`);
+    }
+    const now = nowISO();
+    assignment.last_heartbeat_at = now;
+    assignment.updated_at = now;
+    if (options.message)
+        assignment.status_reason = options.message;
+    if (options.artifacts?.length) {
+        assignment.artifacts = [...assignment.artifacts, ...options.artifacts];
+    }
+    saveAssignment(assignment, cwd);
+    emitAssignmentEvent(assignment, 'assignment_progress', options.actor, cwd);
+    try {
+        const latestRun = findLatestAgentRunForAssignment(assignment.id, cwd);
+        if (latestRun) {
+            recordAgentRunProgress(latestRun.id, {
+                message: options.message,
+                artifacts: options.artifacts,
+                actor: options.actor,
+                actor_id: options.actor_id,
+                session_id: options.session_id,
+            }, cwd);
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return assignment;
+}
+/**
+ * Create a new assignment. Called by the dispatcher after creating a claim
+ * and sending an inbox message.
+ */
+export function createAssignment(options, cwd) {
+    const generated = options.id ? undefined : generateAssignmentId(cwd);
+    const id = options.id ?? generated.id;
+    const short_label = options.short_label ?? generated.short_label;
+    const assignment = AssignmentSchema.parse({
+        schema_version: 1,
+        id,
+        short_label,
+        claim_id: options.claim_id,
+        message_id: options.message_id,
+        plan_id: options.plan_id,
+        sequence_id: options.sequence_id,
+        correlation_id: options.correlation_id,
+        agent: options.agent,
+        agent_id: options.agent_id,
+        dispatcher_agent: options.dispatcher_agent,
+        dispatcher_session_id: options.dispatcher_session_id,
+        scope: options.scope,
+        description: options.description,
+        lane: options.lane,
+        worktree_path: options.worktree_path,
+        status: 'created',
+        created_at: nowISO(),
+        heartbeat_ttl_ms: options.heartbeat_ttl_ms,
+        acceptance_ttl_ms: options.acceptance_ttl_ms,
+        max_retries: options.max_retries,
+        retry_count: 0,
+        artifacts: [],
+        tags: options.tags ?? [],
+    });
+    saveAssignment(assignment, cwd);
+    emitAssignmentEvent(assignment, 'assignment_created', options.dispatcher_agent, cwd);
+    appendAuditEntry({
+        actor: options.dispatcher_agent,
+        action: 'create',
+        item_id: assignment.id,
+        item_type: 'assignment',
+        after: { agent: options.agent, scope: options.scope, claim_id: options.claim_id },
+    }, cwd);
+    return assignment;
+}
+// ── Active Assignment Lookup ─────────────────────────────────
+/** Statuses that indicate a finished assignment (no longer active). */
+const TERMINAL_STATUSES = new Set(['completed', 'expired', 'rerouted']);
+/**
+ * Return the most recently created non-terminal assignment for the given agent.
+ * When `claimId` is provided, it is used as a fast-path lookup before falling
+ * back to an agent-wide scan.
+ */
+export function getActiveAssignmentForAgent(agentId, cwd, claimId) {
+    if (claimId) {
+        const byClaim = listAssignments(cwd, { claim_id: claimId });
+        const active = byClaim.filter((a) => !TERMINAL_STATUSES.has(a.status));
+        // listAssignments returns ascending-by-created_at — last is most recent
+        if (active.length > 0)
+            return active[active.length - 1];
+    }
+    if (!agentId)
+        return undefined;
+    const all = listAssignments(cwd);
+    const active = all.filter((a) => a.agent_id === agentId && !TERMINAL_STATUSES.has(a.status));
+    return active.length > 0 ? active[active.length - 1] : undefined;
+}
+/**
+ * Bump `last_heartbeat_at` on the most recent active assignment for the given
+ * claim (or agent). Best-effort — throws are suppressed by the caller.
+ */
+export function bumpActiveAssignmentHeartbeat(claimId, agentId, cwd) {
+    const assignment = getActiveAssignmentForAgent(agentId ?? '', cwd, claimId);
+    if (!assignment)
+        return false;
+    const now = nowISO();
+    assignment.last_heartbeat_at = now;
+    assignment.updated_at = now;
+    saveAssignment(assignment, cwd);
+    return true;
+}
+// ── Post-creation patches ────────────────────────────────────
+/** Attach the inbox message_id after the message has been sent (message is created after assignment). */
+export function patchAssignmentMessageId(id, messageId, cwd) {
+    const assignment = loadAssignment(id, cwd);
+    if (!assignment)
+        return;
+    assignment.message_id = messageId;
+    saveAssignment(assignment, cwd);
+}
+// ── Event Emission ───────────────────────────────────────────
+function emitAssignmentEvent(assignment, action, actor, cwd) {
+    const text = `${assignment.description} [${assignment.status}]${assignment.status_reason ? ` — ${assignment.status_reason}` : ''}`;
+    appendEvent({
+        ts: nowISO(),
+        agent: actor ?? assignment.agent,
+        agent_id: assignment.agent_id,
+        action: action,
+        item_type: 'assignment',
+        item_id: assignment.id,
+        summary: `${assignment.status}: ${assignment.description.slice(0, 80)}`,
+    }, cwd);
+    try {
+        createRuntimeEvent({
+            agent: actor ?? assignment.agent,
+            agent_id: assignment.agent_id,
+            project_id: undefined,
+            session_id: assignment.session_id,
+            event_type: action,
+            text,
+            tags: ['agent-runtime', 'assignment'],
+            assignment_id: assignment.id,
+            claim_id: assignment.claim_id,
+            message_id: assignment.message_id,
+            plan_id: assignment.plan_id,
+            sequence_id: assignment.sequence_id,
+            correlation_id: assignment.correlation_id,
+            scope: assignment.scope,
+            status: assignment.status,
+            status_reason: assignment.status_reason,
+            related_paths: [assignment.scope],
+            metadata: {
+                dispatcher_agent: assignment.dispatcher_agent,
+                protocol: 'brainclaw.agent_runtime.v0',
+            },
+        }, cwd);
+    }
+    catch {
+        /* best-effort: runtime event emission should not break assignment lifecycle */
+    }
+}
+//# sourceMappingURL=assignments.js.map

package/dist/core/audit.js

@@ -6,6 +6,7 @@ import { nowISO } from './ids.js';
 import { logger } from './logger.js';
 import { appendEvent } from './event-log.js';
 const AUDIT_LOG_FILE = 'audit.log';
+const MAX_AUDIT_LOG_BYTES = 10 * 1024 * 1024; // 10MB
 /** Map audit actions to event-log actions (subset that overlaps) */
 const AUDIT_TO_EVENT_ACTION = {
     create: 'create',
@@ -18,6 +19,8 @@ const AUDIT_TO_EVENT_ACTION = {
     session_start: 'session_start',
     session_end: 'session_end',
     rollback: 'rollback',
+    promote_direct: 'create',
+    trust_change: 'update',
 };
 function auditLogPath(cwd) {
     return path.join(memoryDir(cwd), AUDIT_LOG_FILE);
@@ -25,6 +28,7 @@ function auditLogPath(cwd) {
 export function appendAuditEntry(entry, cwd) {
     try {
         mutate({ cwd }, () => {
+            rotateAuditLogIfNeeded(cwd);
             const full = {
                 timestamp: nowISO(),
                 actor: entry.actor,
@@ -35,6 +39,10 @@ export function appendAuditEntry(entry, cwd) {
                 after: entry.after,
                 actor_id: entry.actor_id,
                 reason: entry.reason,
+                scope: entry.scope,
+                session_id: entry.session_id,
+                host_id: entry.host_id,
+                actor_session: entry.actor_session,
             };
             const line = JSON.stringify(Object.fromEntries(Object.entries(full).filter(([, v]) => v !== undefined)));
             fs.appendFileSync(auditLogPath(cwd), line + '\n', 'utf-8');
@@ -83,4 +91,26 @@ export function readAuditLog(options = {}, cwd) {
     }
     return entries;
 }
+/**
+ * Rotate audit.log if it exceeds MAX_AUDIT_LOG_BYTES.
+ * Archives to audit.{timestamp}.log in the same directory.
+ */
+export function rotateAuditLogIfNeeded(cwd) {
+    const logPath = auditLogPath(cwd);
+    if (!fs.existsSync(logPath))
+        return false;
+    try {
+        const stat = fs.statSync(logPath);
+        if (stat.size < MAX_AUDIT_LOG_BYTES)
+            return false;
+        const archiveName = `audit.${Date.now()}.log`;
+        const archivePath = path.join(memoryDir(cwd), archiveName);
+        fs.renameSync(logPath, archivePath);
+        return true;
+    }
+    catch (err) {
+        logger.debug('Failed to rotate audit log:', err);
+        return false;
+    }
+}
 //# sourceMappingURL=audit.js.map

package/dist/core/brainclaw-version.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { BrainclawLocalReleaseManifestSchema, } from './schema.js';
+import { AgentReleaseNotesSchema, BrainclawLocalReleaseManifestSchema, } from './schema.js';
 export const DEFAULT_LOCAL_RELEASES_DIR = '.releases';
 export const DEFAULT_LOCAL_RELEASE_MANIFEST_PATH = `${DEFAULT_LOCAL_RELEASES_DIR}/brainclaw-local.json`;
 export const DEFAULT_NPM_UPDATE_PACKAGE = 'brainclaw';
@@ -15,7 +15,75 @@ const DEFAULT_NPM_UPDATE_SOURCE = {
     package_name: DEFAULT_NPM_UPDATE_PACKAGE,
     dist_tag: DEFAULT_NPM_UPDATE_DIST_TAG,
 };
+/**
+ * Scan PATH for all brainclaw installations and their versions.
+ * Detects when multiple versions are installed (e.g. global + user-local)
+ * which causes confusion about which version is actually running.
+ */
+export function detectConcurrentInstallations() {
+    const currentVersion = getInstalledBrainclawVersion();
+    const installations = [];
+    const seen = new Set();
+    // On Windows, `where` returns all matches. On Unix, `which -a` does.
+    const isWindows = os.platform() === 'win32';
+    const result = isWindows
+        ? spawnSync('where', ['brainclaw'], { encoding: 'utf-8', timeout: 5000 })
+        : spawnSync('which', ['-a', 'brainclaw'], { encoding: 'utf-8', timeout: 5000 });
+    if (result.status !== 0)
+        return [];
+    const paths = result.stdout.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+    for (const binPath of paths) {
+        // Normalize to avoid duplicates from symlinks
+        let realPath;
+        try {
+            realPath = isWindows ? binPath : fs.realpathSync(binPath);
+        }
+        catch {
+            realPath = binPath;
+        }
+        if (seen.has(realPath))
+            continue;
+        seen.add(realPath);
+        // Get version by running the binary
+        let version = 'unknown';
+        try {
+            const vResult = spawnSync(binPath, ['--version'], { encoding: 'utf-8', timeout: 5000 });
+            if (vResult.status === 0) {
+                version = vResult.stdout.trim().split(/\r?\n/)[0]?.trim() ?? 'unknown';
+            }
+        }
+        catch { /* ignore */ }
+        installations.push({
+            path: binPath,
+            version,
+            isCurrent: version === currentVersion,
+        });
+    }
+    return installations;
+}
 let cachedCliVersion;
+let cachedPackageJsonPath;
+/**
+ * Read the brainclaw version from disk (package.json), bypassing the in-memory cache.
+ * Used by the MCP server to detect when a new version has been installed while the
+ * long-running MCP process is still running with old code.
+ */
+export function readDiskBrainclawVersion() {
+    if (cachedPackageJsonPath === undefined) {
+        cachedPackageJsonPath = findOwnPackageJson() ?? '';
+    }
+    if (!cachedPackageJsonPath)
+        return '0.0.0';
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachedPackageJsonPath, 'utf-8'));
+        return typeof parsed.version === 'string' && parsed.version.trim().length > 0
+            ? parsed.version.trim()
+            : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
 export function getInstalledBrainclawVersion() {
     if (cachedCliVersion) {
         return cachedCliVersion;
@@ -126,7 +194,23 @@ export function renderBrainclawInstallableUpdateNotice(updateCheck) {
     if (updateCheck.install_command) {
         lines.push(`Install: ${updateCheck.install_command}`);
     }
-    if (updateCheck.release_notes) {
+    const arn = updateCheck.agent_release_notes;
+    if (arn) {
+        lines.push(`Summary: ${arn.summary}`);
+        if (arn.breaking_risk && arn.breaking_risk !== 'none') {
+            lines.push(`Breaking risk: ${arn.breaking_risk}`);
+        }
+        if (arn.highlights && arn.highlights.length > 0) {
+            lines.push('Highlights:');
+            for (const h of arn.highlights) {
+                lines.push(`  • ${h}`);
+            }
+        }
+        if (arn.action_recommendation) {
+            lines.push(`Action: ${arn.action_recommendation}`);
+        }
+    }
+    else if (updateCheck.release_notes) {
         lines.push(`Why update: ${updateCheck.release_notes}`);
     }
     return lines.join('\n');
@@ -161,6 +245,9 @@ export function publishLocalBrainclawRelease(cwd, options = {}) {
     const projectManifestPath = toPortablePath(path.relative(cwd, manifestPath));
     const installCommand = `npm install -g "${projectArtifactPath}"`;
     const releaseNotes = options.releaseNotes?.trim() || null;
+    const agentReleaseNotes = options.agentReleaseNotes
+        ? AgentReleaseNotesSchema.parse(options.agentReleaseNotes)
+        : null;
     const manifest = BrainclawLocalReleaseManifestSchema.parse({
         version: 1,
         channel: 'local-pack',
@@ -170,6 +257,7 @@ export function publishLocalBrainclawRelease(cwd, options = {}) {
         artifact_path: manifestArtifactPath,
         install_command: installCommand,
         release_notes: releaseNotes ?? undefined,
+        agent_release_notes: agentReleaseNotes ?? undefined,
     });
     fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
     return {
@@ -179,6 +267,7 @@ export function publishLocalBrainclawRelease(cwd, options = {}) {
         artifact_path: projectArtifactPath,
         install_command: installCommand,
         release_notes: releaseNotes,
+        agent_release_notes: agentReleaseNotes,
     };
 }
 function checkNpmInstallableUpdate(source, config, cwd, options, defaultSource) {
@@ -343,6 +432,7 @@ function checkLocalPackInstallableUpdate(manifestPath, config, cwd) {
         const installCommand = manifest.install_command?.trim()
             || (artifactPath ? `npm install -g "${artifactPath}"` : config?.brainclaw_upgrade_command?.trim() || null);
         const releaseNotes = manifest.release_notes?.trim() || config?.brainclaw_upgrade_message?.trim() || null;
+        const agentReleaseNotes = manifest.agent_release_notes ?? null;
         const installedVersion = getInstalledBrainclawVersion();
         if (compareVersions(installedVersion, latestVersion) < 0) {
             return {
@@ -353,6 +443,7 @@ function checkLocalPackInstallableUpdate(manifestPath, config, cwd) {
                 artifact_path: artifactPath,
                 install_command: installCommand,
                 release_notes: releaseNotes,
+                agent_release_notes: agentReleaseNotes,
                 status: 'update_available',
                 message: `A newer installable brainclaw build is available: ${latestVersion} (installed ${installedVersion}).`,
                 default_source: false,
@@ -366,6 +457,7 @@ function checkLocalPackInstallableUpdate(manifestPath, config, cwd) {
             artifact_path: artifactPath,
             install_command: installCommand,
             release_notes: releaseNotes,
+            agent_release_notes: agentReleaseNotes,
             status: 'up_to_date',
             message: `Installed brainclaw ${installedVersion} is up to date for the configured local-pack channel.`,
             default_source: false,