brainclaw 0.29.2 → 1.5.4

package/dist/core/loops/verbs.js

@@ -0,0 +1,534 @@
+import crypto from 'node:crypto';
+import { nowISO } from '../ids.js';
+import { appendEvent, generateMutationId, getLoop, listLoopEvents, writeThreadFile, } from './store.js';
+import { LoopArtifactSchema, } from './types.js';
+import { decideNextPhase, } from './iteration-engine.js';
+function nextSeq(loopId, cwd) {
+    const events = listLoopEvents(loopId, cwd);
+    return (events[events.length - 1]?.seq ?? 0) + 1;
+}
+function assertMutable(thread, intent) {
+    if (thread.status === 'completed' || thread.status === 'cancelled' || thread.status === 'blocked') {
+        throw new Error(`${intent}: loop ${thread.id} is already ${thread.status}`);
+    }
+}
+function loadLoopOrThrow(id, cwd) {
+    const loop = getLoop(id, cwd);
+    if (!loop)
+        throw new Error(`unknown loop_id ${id}`);
+    return loop;
+}
+/* ========================= Stop-condition evaluator ======================= */
+function isVerdictAccepted(artifact) {
+    if (artifact.type !== 'verdict')
+        return false;
+    const body = (artifact.body ?? '').trim().toLowerCase();
+    return /^accepted(?:\b|[:\s])/.test(body);
+}
+export function evaluateStopCondition(thread, condition) {
+    if (!condition)
+        return false;
+    switch (condition.kind) {
+        case 'phase_reached':
+            return thread.current_phase === condition.phase;
+        case 'reviewer_green':
+            return thread.artifacts.some(isVerdictAccepted);
+        case 'max_iterations':
+            return thread.iteration_count >= condition.n;
+        case 'artifact_produced':
+            return thread.artifacts.some((artifact) => artifact.phase === condition.phase && artifact.type === condition.type);
+        case 'min_artifacts_by_type': {
+            // pln#492 — count artifacts of `type` in the requested scope.
+            // Phase scope counts artifacts whose phase matches the thread's
+            // current_phase. When the thread is iterating (iteration_count > 0
+            // OR any artifact carries an iteration field), phase scope is
+            // refined to the current iteration window — that's what makes
+            // "≥3 critiques in current critique round" work without the
+            // previous round leaking in. loop scope counts across all phases
+            // and all iterations.
+            const matches = thread.artifacts.filter((artifact) => {
+                if (artifact.type !== condition.type)
+                    return false;
+                if (condition.scope === 'phase') {
+                    if (artifact.phase !== thread.current_phase)
+                        return false;
+                    // pln#492 phase 2.b — iteration-window awareness. If either the
+                    // thread or the artifact carries iteration info, only count the
+                    // artifacts produced in the thread's current iteration. Legacy
+                    // loops without iteration tracking are unaffected (both fields
+                    // default to 0).
+                    if (thread.iteration_count > 0 ||
+                        thread.artifacts.some((a) => a.iteration !== undefined)) {
+                        const artifactIteration = artifact.iteration ?? 0;
+                        if (artifactIteration !== thread.iteration_count)
+                            return false;
+                    }
+                    return true;
+                }
+                return true;
+            });
+            return matches.length >= condition.n;
+        }
+        case 'manual':
+            return false;
+        case 'any':
+            return condition.conditions.some((c) => evaluateStopCondition(thread, c));
+        case 'all':
+            return condition.conditions.every((c) => evaluateStopCondition(thread, c));
+        default: {
+            const exhaustive = condition;
+            void exhaustive;
+            return false;
+        }
+    }
+}
+export function evaluatePhaseAdvanceGate(thread, gate) {
+    if (!gate)
+        return { advance: true };
+    if (evaluateStopCondition(thread, gate))
+        return { advance: true };
+    return {
+        advance: false,
+        gate_reason: describeUnmetGate(thread, gate),
+    };
+}
+function describeUnmetGate(thread, gate) {
+    switch (gate.kind) {
+        case 'min_artifacts_by_type': {
+            // Mirror the iteration-aware filter used in evaluateStopCondition so
+            // the message's count matches what the evaluator actually saw — the
+            // operator should not see "count=4" in an error from a gate that
+            // counted only iteration=1 artifacts.
+            const iterationAware = thread.iteration_count > 0 ||
+                thread.artifacts.some((a) => a.iteration !== undefined);
+            const matches = thread.artifacts.filter((artifact) => {
+                if (artifact.type !== gate.type)
+                    return false;
+                if (gate.scope === 'phase') {
+                    if (artifact.phase !== thread.current_phase)
+                        return false;
+                    if (iterationAware) {
+                        const artifactIteration = artifact.iteration ?? 0;
+                        if (artifactIteration !== thread.iteration_count)
+                            return false;
+                    }
+                    return true;
+                }
+                return true;
+            });
+            return `min_artifacts_by_type unmet: ${gate.scope}-scope count of type "${gate.type}" = ${matches.length} < n=${gate.n}`;
+        }
+        case 'phase_reached':
+            return `phase_reached unmet: current_phase="${thread.current_phase}" expected="${gate.phase}"`;
+        case 'reviewer_green':
+            return 'reviewer_green unmet: no accepted verdict artifact yet';
+        case 'max_iterations':
+            return `max_iterations unmet: iteration_count=${thread.iteration_count} < n=${gate.n}`;
+        case 'artifact_produced':
+            return `artifact_produced unmet: no artifact of type "${gate.type}" in phase "${gate.phase}"`;
+        case 'manual':
+            return 'manual gate: caller did not signal advance';
+        case 'any':
+            return `any-of unmet: none of ${gate.conditions.length} sub-conditions held`;
+        case 'all':
+            return `all-of unmet: at least one of ${gate.conditions.length} sub-conditions failed`;
+        default: {
+            const exhaustive = gate;
+            void exhaustive;
+            return 'unknown gate kind';
+        }
+    }
+}
+function stopHitsBlock(condition) {
+    if (!condition)
+        return false;
+    if (condition.kind === 'max_iterations')
+        return true;
+    if (condition.kind === 'any' || condition.kind === 'all') {
+        return condition.conditions.some(stopHitsBlock);
+    }
+    return false;
+}
+export function advance(input, cwd) {
+    const current = loadLoopOrThrow(input.id, cwd);
+    assertMutable(current, 'advance');
+    if (current.status === 'paused') {
+        throw new Error(`advance: loop ${current.id} is paused; resume before advancing`);
+    }
+    const phaseNames = current.phases.map((p) => p.name);
+    const currentIndex = phaseNames.indexOf(current.current_phase);
+    if (currentIndex < 0) {
+        throw new Error(`advance: current_phase "${current.current_phase}" is not in phases`);
+    }
+    // pln#492 phase 2.b — phase-advance gate check. Skipped when the caller
+    // is forcing an explicit to_phase or passing { force: true }. On block,
+    // emit a `phase_advance_blocked` system event into the journal and throw
+    // an actionable error (not a silent hang — mitigates trp#160 wiring class).
+    if (input.to_phase === undefined && input.force !== true) {
+        const currentPhaseDef = current.phases[currentIndex];
+        const gate = currentPhaseDef?.advance_gate;
+        const gateOutcome = evaluatePhaseAdvanceGate(current, gate);
+        if (!gateOutcome.advance) {
+            const blockSeq = nextSeq(current.id, cwd);
+            const blockMutation = generateMutationId();
+            appendEvent(current.id, {
+                event_id: crypto.randomUUID(),
+                loop_id: current.id,
+                seq: blockSeq,
+                at: nowISO(),
+                by: input.actor,
+                mutation_id: blockMutation,
+                kind: 'phase_advance_blocked',
+                phase: current.current_phase,
+                gate_reason: gateOutcome.gate_reason ?? 'gate evaluation returned no reason',
+            }, cwd);
+            throw new Error(`advance: phase_advance_blocked on "${current.current_phase}" — ${gateOutcome.gate_reason}`);
+        }
+    }
+    // Decide the next state. If the caller specified a to_phase, honour it
+    // verbatim (used by `force`-style overrides and explicit jumps). Otherwise
+    // consult the iteration engine, which knows about the cycle, exit_when,
+    // and the iteration cap.
+    let to_phase;
+    let iteration_count = current.iteration_count;
+    let iterationDecision;
+    if (input.to_phase !== undefined) {
+        if (!phaseNames.includes(input.to_phase)) {
+            throw new Error(`advance: to_phase "${input.to_phase}" is not in phases`);
+        }
+        to_phase = input.to_phase;
+        const toIndex = phaseNames.indexOf(to_phase);
+        const iteratingBackward = toIndex <= currentIndex;
+        // Going backward via explicit to_phase is allowed (it bumps the
+        // iteration counter so callers can hand-roll their own iteration when
+        // they don't have an iteration block defined). The forward-direction
+        // restriction only applies when no to_phase is given.
+        if (iteratingBackward)
+            iteration_count = current.iteration_count + 1;
+    }
+    else {
+        const protocol = {
+            phases: current.phases,
+            iteration: current.protocol?.iteration,
+        };
+        iterationDecision = decideNextPhase(current, protocol);
+        to_phase = iterationDecision.target;
+        iteration_count = iterationDecision.iteration;
+    }
+    if (evaluateStopCondition(current, current.stop_condition)) {
+        const finalStatus = stopHitsMaxIterations(current, current.stop_condition)
+            ? 'blocked'
+            : 'completed';
+        const closed = commitClosedTransition(current, finalStatus, input.actor, input.reason, cwd);
+        return { loop: closed, auto_closed: true };
+    }
+    const now = nowISO();
+    const mutation_id = generateMutationId();
+    const version = current.version + 1;
+    let seq = nextSeq(current.id, cwd);
+    const next = {
+        ...current,
+        version,
+        mutation_id,
+        current_phase: to_phase,
+        iteration_count,
+        updated_at: now,
+    };
+    // pln#492 phase 2.b — when the iteration engine forces the cycle out
+    // because the cap was hit, emit `max_iterations_reached` BEFORE the
+    // phase_advanced event so the journal reads in causal order.
+    if (iterationDecision?.kind === 'max_iterations') {
+        appendEvent(current.id, {
+            event_id: crypto.randomUUID(),
+            loop_id: current.id,
+            seq,
+            at: now,
+            by: input.actor,
+            mutation_id,
+            kind: 'max_iterations_reached',
+            phase: current.current_phase,
+            iteration: iterationDecision.iteration,
+            max_iterations: iterationDecision.max,
+        }, cwd);
+        seq = nextSeq(current.id, cwd);
+    }
+    appendEvent(current.id, {
+        event_id: crypto.randomUUID(),
+        loop_id: current.id,
+        seq,
+        at: now,
+        by: input.actor,
+        mutation_id,
+        kind: 'phase_advanced',
+        from_phase: current.current_phase,
+        to_phase,
+        iteration: iteration_count,
+        reason: input.reason,
+    }, cwd);
+    writeThreadFile(next, cwd);
+    const postAdvance = evaluateStopCondition(next, next.stop_condition);
+    if (postAdvance) {
+        const finalStatus = stopHitsMaxIterations(next, next.stop_condition)
+            ? 'blocked'
+            : 'completed';
+        const closed = commitClosedTransition(next, finalStatus, input.actor, input.reason, cwd);
+        return { loop: closed, auto_closed: true };
+    }
+    return { loop: next, auto_closed: false };
+}
+function stopHitsMaxIterations(thread, condition) {
+    if (!condition)
+        return false;
+    if (!stopHitsBlock(condition))
+        return false;
+    if (condition.kind === 'max_iterations') {
+        return thread.iteration_count >= condition.n;
+    }
+    if (condition.kind === 'any' || condition.kind === 'all') {
+        return condition.conditions.some((c) => stopHitsMaxIterations(thread, c));
+    }
+    return false;
+}
+function commitClosedTransition(thread, final_status, actor, reason, cwd) {
+    const now = nowISO();
+    const mutation_id = generateMutationId();
+    const version = thread.version + 1;
+    const seq = nextSeq(thread.id, cwd);
+    const next = {
+        ...thread,
+        version,
+        mutation_id,
+        status: final_status,
+        updated_at: now,
+        closed_at: now,
+    };
+    appendEvent(thread.id, {
+        event_id: crypto.randomUUID(),
+        loop_id: thread.id,
+        seq,
+        at: now,
+        by: actor,
+        mutation_id,
+        kind: 'closed',
+        final_status,
+        reason,
+    }, cwd);
+    writeThreadFile(next, cwd);
+    return next;
+}
+function resolveTurnSlot(thread, input) {
+    if (input.slot_id) {
+        const match = thread.slots.find((s) => s.slot_id === input.slot_id);
+        if (!match)
+            throw new Error(`turn: slot_id "${input.slot_id}" not in loop`);
+        return match;
+    }
+    if (input.role) {
+        const match = thread.slots.find((s) => s.role === input.role && s.status !== 'done');
+        if (!match)
+            throw new Error(`turn: no active slot with role "${input.role}"`);
+        return match;
+    }
+    throw new Error(`turn: either slot_id or role must be supplied`);
+}
+export function turn(input, cwd) {
+    const current = loadLoopOrThrow(input.id, cwd);
+    assertMutable(current, 'turn');
+    if (current.status === 'paused')
+        throw new Error(`turn: loop ${current.id} is paused`);
+    const targetSlot = resolveTurnSlot(current, input);
+    const now = nowISO();
+    const mutation_id = generateMutationId();
+    const version = current.version + 1;
+    const seq = nextSeq(current.id, cwd);
+    const updatedSlots = current.slots.map((slot) => slot.slot_id === targetSlot.slot_id
+        ? {
+            ...slot,
+            status: 'assigned',
+            phase: current.current_phase,
+            assignment_id: input.assignment_id ?? slot.assignment_id,
+        }
+        : slot);
+    const next = {
+        ...current,
+        version,
+        mutation_id,
+        slots: updatedSlots,
+        updated_at: now,
+    };
+    appendEvent(current.id, {
+        event_id: crypto.randomUUID(),
+        loop_id: current.id,
+        seq,
+        at: now,
+        by: input.actor,
+        mutation_id,
+        kind: 'turn_assigned',
+        slot_id: targetSlot.slot_id,
+        phase: current.current_phase,
+        assignment_id: input.assignment_id,
+        input: input.input,
+    }, cwd);
+    writeThreadFile(next, cwd);
+    return next;
+}
+export function complete_turn(input, cwd) {
+    const current = loadLoopOrThrow(input.id, cwd);
+    assertMutable(current, 'complete_turn');
+    const slot = current.slots.find((s) => s.slot_id === input.slot_id);
+    if (!slot)
+        throw new Error(`complete_turn: slot_id "${input.slot_id}" not in loop`);
+    // Slot-bound auth. Only enforced when caller_agent_id is supplied (MCP entry path).
+    if (input.caller_agent_id !== undefined && !input.admin_override) {
+        const ownerMatches = slot.agent_id !== undefined && slot.agent_id === input.caller_agent_id;
+        const creatorMatches = current.created_by === input.caller_agent_id;
+        if (!ownerMatches && !creatorMatches) {
+            throw new Error('unauthorized_slot_write');
+        }
+    }
+    const now = nowISO();
+    const mutation_id = generateMutationId();
+    const version = current.version + 1;
+    const outcome = input.outcome ?? 'done';
+    let nextArtifacts = current.artifacts;
+    let artifactId;
+    if (input.artifact) {
+        const newArtifact = LoopArtifactSchema.parse({
+            ...input.artifact,
+            artifact_id: `art_${crypto.randomBytes(6).toString('hex')}`,
+            produced_by: slot.slot_id,
+            produced_at: now,
+        });
+        artifactId = newArtifact.artifact_id;
+        nextArtifacts = [...nextArtifacts, newArtifact];
+    }
+    // Map outcome → terminal slot.status so observers reading the thread can
+    // distinguish done/failed/cancelled without replaying the event journal.
+    const terminalStatus = outcome;
+    const updatedSlots = current.slots.map((s) => s.slot_id === slot.slot_id ? { ...s, status: terminalStatus } : s);
+    const next = {
+        ...current,
+        version,
+        mutation_id,
+        slots: updatedSlots,
+        artifacts: nextArtifacts,
+        updated_at: now,
+    };
+    const events = [];
+    if (artifactId && input.artifact) {
+        events.push({
+            event_id: crypto.randomUUID(),
+            loop_id: current.id,
+            seq: nextSeq(current.id, cwd),
+            at: now,
+            by: input.actor,
+            mutation_id,
+            kind: 'artifact_added',
+            artifact_id: artifactId,
+            phase: input.artifact.phase,
+            type: input.artifact.type,
+            produced_by: slot.slot_id,
+        });
+    }
+    events.push({
+        event_id: crypto.randomUUID(),
+        loop_id: current.id,
+        seq: nextSeq(current.id, cwd) + events.length,
+        at: now,
+        by: input.actor,
+        mutation_id,
+        kind: 'turn_completed',
+        slot_id: slot.slot_id,
+        phase: slot.phase ?? current.current_phase,
+        artifact_id: artifactId,
+        outcome,
+        failure_reason: input.failure_reason,
+    });
+    for (const event of events)
+        appendEvent(current.id, event, cwd);
+    writeThreadFile(next, cwd);
+    return next;
+}
+export function add_artifact(input, cwd) {
+    const current = loadLoopOrThrow(input.id, cwd);
+    assertMutable(current, 'add_artifact');
+    const now = nowISO();
+    const mutation_id = generateMutationId();
+    const version = current.version + 1;
+    const seq = nextSeq(current.id, cwd);
+    // pln#492 phase 2.b — auto-populate iteration from the thread's current
+    // iteration_count when the caller didn't supply one. Iterating loops get
+    // accurate per-iteration counts without callers having to track the
+    // index; non-iterating loops are unaffected because iteration_count
+    // stays at 0.
+    const newArtifact = LoopArtifactSchema.parse({
+        ...input.artifact,
+        artifact_id: `art_${crypto.randomBytes(6).toString('hex')}`,
+        produced_at: now,
+        iteration: input.artifact.iteration ?? current.iteration_count,
+    });
+    const next = {
+        ...current,
+        version,
+        mutation_id,
+        artifacts: [...current.artifacts, newArtifact],
+        updated_at: now,
+    };
+    appendEvent(current.id, {
+        event_id: crypto.randomUUID(),
+        loop_id: current.id,
+        seq,
+        at: now,
+        by: input.actor,
+        mutation_id,
+        kind: 'artifact_added',
+        artifact_id: newArtifact.artifact_id,
+        phase: newArtifact.phase,
+        type: newArtifact.type,
+        produced_by: newArtifact.produced_by,
+    }, cwd);
+    writeThreadFile(next, cwd);
+    return next;
+}
+export function pause(input, cwd) {
+    const current = loadLoopOrThrow(input.id, cwd);
+    if (current.status !== 'open') {
+        throw new Error(`pause: loop ${current.id} is ${current.status}, not open`);
+    }
+    return commitSimpleStatus(current, 'paused', 'paused', input.actor, input.reason, cwd);
+}
+export function resume(input, cwd) {
+    const current = loadLoopOrThrow(input.id, cwd);
+    if (current.status !== 'paused') {
+        throw new Error(`resume: loop ${current.id} is ${current.status}, not paused`);
+    }
+    return commitSimpleStatus(current, 'open', 'resumed', input.actor, input.reason, cwd);
+}
+function commitSimpleStatus(current, newStatus, eventKind, actor, reason, cwd) {
+    const now = nowISO();
+    const mutation_id = generateMutationId();
+    const version = current.version + 1;
+    const seq = nextSeq(current.id, cwd);
+    const next = {
+        ...current,
+        version,
+        mutation_id,
+        status: newStatus,
+        updated_at: now,
+    };
+    const base = {
+        event_id: crypto.randomUUID(),
+        loop_id: current.id,
+        seq,
+        at: now,
+        by: actor,
+        mutation_id,
+    };
+    const event = eventKind === 'paused'
+        ? { ...base, kind: 'paused', reason }
+        : { ...base, kind: 'resumed' };
+    appendEvent(current.id, event, cwd);
+    writeThreadFile(next, cwd);
+    return next;
+}
+//# sourceMappingURL=verbs.js.map

package/dist/core/markdown.js

@@ -101,11 +101,18 @@ export function generateMarkdown(state, cwd) {
     }
     lines.push('');
     lines.push('## Open handoffs');
-    if (state.open_handoffs.length === 0) {
+    const MAX_HANDOFFS = 10;
+    const MAX_HANDOFF_TEXT = 500;
+    const activeHandoffs = state.open_handoffs
+        .filter((h) => h.status === 'open')
+        .sort((a, b) => b.created_at.localeCompare(a.created_at))
+        .slice(0, MAX_HANDOFFS);
+    const totalOpen = state.open_handoffs.filter((h) => h.status === 'open').length;
+    if (activeHandoffs.length === 0) {
         lines.push('- (none)');
     }
     else {
-        for (const h of state.open_handoffs) {
+        for (const h of activeHandoffs) {
             const tags = h.tags.length ? ` [${h.tags.join(', ')}]` : '';
             const paths = h.related_paths?.length ? ` → ${h.related_paths.join(', ')}` : '';
             const meta = [h.status];
@@ -113,7 +120,12 @@ export function generateMarkdown(state, cwd) {
                 meta.push(`plan: ${h.plan_id}`);
             if (h.project)
                 meta.push(`project: ${h.project}`);
-            lines.push(`- **[${h.id}]** ${h.from} → ${h.to}: ${h.text} _(${meta.join(', ')})_${paths}${tags}`);
+            const text = h.text.length > MAX_HANDOFF_TEXT ? h.text.slice(0, MAX_HANDOFF_TEXT) + '...' : h.text;
+            lines.push(`- **[${h.id}]** ${h.from} → ${h.to}: ${text} _(${meta.join(', ')})_${paths}${tags}`);
+        }
+        const omitted = totalOpen - activeHandoffs.length;
+        if (omitted > 0) {
+            lines.push(`- _(${omitted} older handoffs omitted — use \`bclaw_read_handoff\` to inspect)_`);
         }
     }
     lines.push('');