brainclaw 1.5.5 → 1.6.0

package/dist/core/loops/store.js

@@ -3,7 +3,9 @@ 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';
+import { writeProjectMdSafe } from './hooks/bootstrap-write.js';
+import { notifyOperatorOnInputRequested } from './hooks/notify-operator.js';
+import { DEFAULT_PROTOCOLS, LoopArtifactSchema, LoopEventSchema, LoopThreadSchema, } from './types.js';
 function loopsDir(cwd) {
     return path.join(memoryDir(cwd ?? process.cwd()), 'loops');
 }
@@ -66,10 +68,35 @@ function buildSlot(partial) {
         status: partial.status ?? 'open',
     };
 }
-export function appendEvent(loopId, event, cwd) {
+export function appendEvent(loopId, event, cwd, 
+/**
+ * pln#513 Phase 4 codex review fix — callers can pass the in-memory next
+ * thread snapshot when they're about to write it. Without this, the
+ * notification hook's `getLoop(loopId)` read sees the PREVIOUS thread
+ * because `appendEvent` runs before `writeThreadFile` at the verb call
+ * sites — meaning the just-added operator_question artifact isn't
+ * reachable, and the OS notification can't include the question text.
+ * Optional + additive: existing callers (and future ones that don't
+ * benefit) keep the disk-read fallback below.
+ */
+threadSnapshot) {
     const parsed = LoopEventSchema.parse(event);
     ensureLoopsDir(cwd);
     fs.appendFileSync(eventsPath(loopId, cwd), `${JSON.stringify(parsed)}\n`);
+    // pln#513 step 4 — best-effort OS notification on input_requested events.
+    // Prefer the in-memory snapshot from the caller (carries the freshly-
+    // added operator_question). Fall back to a disk read so any direct
+    // appendEvent caller without a snapshot still gets best-effort scoping.
+    if (parsed.kind === 'input_requested') {
+        try {
+            const loop = threadSnapshot ?? getLoop(loopId, cwd);
+            if (loop)
+                notifyOperatorOnInputRequested(parsed, loop, cwd);
+        }
+        catch {
+            // hook is best-effort; never propagate.
+        }
+    }
 }
 export function writeThreadFile(thread, cwd) {
     const parsed = LoopThreadSchema.parse(thread);
@@ -90,7 +117,11 @@ export function openLoop(input, cwd) {
     const id = generateLoopId();
     const mutation_id = generateMutationId();
     const slots = (input.slots ?? []).map(buildSlot);
-    const protocol = resolveProtocol(input.kind, input.mode);
+    // pln#511 step 2 — an explicit `protocol` override (carried by loop
+    // presets) wins over the kind/mode-derived default. When no override
+    // is supplied, fall back to the legacy resolveProtocol() path so
+    // existing callers (review, default ideation) are unaffected.
+    const protocol = input.protocol ?? resolveProtocol(input.kind, input.mode);
     const thread = {
         schema_version: 1,
         id,
@@ -106,6 +137,9 @@ export function openLoop(input, cwd) {
         iteration_count: 0,
         slots,
         artifacts: [],
+        // pln#508 step 1 — bootstrap loop primitives. Default to no open
+        // questions; the request_input handler (step 2) appends/removes ids.
+        open_questions: [],
         linked: input.linked,
         stop_condition: input.stop_condition ?? protocolDefaults.stop_condition,
         created_at: now,
@@ -163,6 +197,73 @@ export function listLoopEvents(id, cwd) {
     const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
     return lines.map((line) => LoopEventSchema.parse(JSON.parse(line)));
 }
+/**
+ * pln#512 step 2 — sentinel thrown by closeLoop when the bootstrap close
+ * hook intercepts an attempt to complete an overwrite of an existing
+ * non-empty PROJECT.md. The thread is left in `status='paused'` with
+ * `pause_reason='awaiting_file_apply'` and a fresh operator_question on
+ * `open_questions`; the caller is expected to surface that question to the
+ * operator, then re-attempt the close once an answer is provided (or rely on
+ * the provideInput post-hook to auto-complete the close — see verbs.ts).
+ *
+ * Thrown with a stable `code` field so callers can `if (e.code ===
+ * 'awaiting_file_apply_approval') ...` instead of string-matching the
+ * message.
+ */
+export class AwaitingFileApplyApprovalError extends Error {
+    loop_id;
+    question_id;
+    target_path;
+    diff_artifact_id;
+    code = 'awaiting_file_apply_approval';
+    constructor(loop_id, question_id, target_path, diff_artifact_id) {
+        super(`closeLoop: awaiting_file_apply_approval — loop ${loop_id} paused on question ${question_id} ` +
+            `for overwrite of ${target_path}; provide_input(replies_to=${question_id}, chosen_option_id=approve|reject) to resolve`);
+        this.loop_id = loop_id;
+        this.question_id = question_id;
+        this.target_path = target_path;
+        this.diff_artifact_id = diff_artifact_id;
+        this.name = 'AwaitingFileApplyApprovalError';
+    }
+}
+/**
+ * pln#512 step 2 — builds the operator_question artifact that asks the
+ * operator whether to overwrite an existing PROJECT.md with the loop's
+ * `project_md_final`. The question shape is fixed (Phase 0 spec §3-5): two
+ * options `approve` / `reject`, default `reject`, pause_scope='loop',
+ * on_timeout='use_default'.
+ *
+ * Returns the (Schema-validated) artifact + its question_id so the caller
+ * can splice it onto the thread and push the id into `open_questions`.
+ */
+function buildFileOverwriteApprovalQuestion(args) {
+    const question_id = `qst_${crypto.randomBytes(6).toString('hex')}`;
+    const body = {
+        question_id,
+        question_text: 'Apply the proposed PROJECT.md diff?',
+        evidence: [
+            `existing PROJECT.md at ${args.target_path}`,
+            `project_md_final artifact ${args.project_md_final_id}`,
+        ],
+        suggested_default: 'reject',
+        options: [
+            { id: 'approve', label: 'Apply diff', tradeoff: 'overwrites current PROJECT.md' },
+            { id: 'reject', label: 'Keep current', tradeoff: 'discards proposed final' },
+        ],
+        pause_scope: 'loop',
+        on_timeout: 'use_default',
+        by_slot_id: args.slot_id,
+    };
+    const artifact = LoopArtifactSchema.parse({
+        artifact_id: `art_${crypto.randomBytes(6).toString('hex')}`,
+        phase: args.phase,
+        type: 'operator_question',
+        body: JSON.stringify(body),
+        produced_by: args.produced_by,
+        produced_at: args.now,
+    });
+    return { artifact, question_id };
+}
 export function closeLoop(input, cwd) {
     const current = getLoop(input.id, cwd);
     if (!current) {
@@ -171,11 +272,124 @@ export function closeLoop(input, cwd) {
     if (current.status !== 'open' && current.status !== 'paused') {
         throw new Error(`closeLoop: loop ${input.id} is already ${current.status}`);
     }
+    // pln#512 step 2 — bootstrap preset close pre-hook. When completing a
+    // bootstrap loop, materialize PROJECT.md from the final artifact:
+    //   - absent / empty target → atomic write, proceed with close.
+    //   - present + non-empty target → pause the close, request operator
+    //     approval for the overwrite; provideInput post-hook resumes + closes.
+    //   - no project_md_final artifact → proceed (nothing to write).
+    //
+    // Only runs when final_status='completed' — cancel/blocked paths skip
+    // the hook because the operator didn't actually converge on a PROJECT.md.
+    const runBootstrapHook = input.final_status === 'completed' && current.protocol?.preset === 'bootstrap';
+    let fileWritten = false;
+    let project_md_final_id;
+    if (runBootstrapHook) {
+        const writeResult = writeProjectMdSafe(current, cwd);
+        // Locate the project_md_final artifact id used by the hook (for the
+        // file_apply_requested / file_apply_resolved event correlation field).
+        for (let i = current.artifacts.length - 1; i >= 0; i--) {
+            if (current.artifacts[i].type === 'project_md_final') {
+                project_md_final_id = current.artifacts[i].artifact_id;
+                break;
+            }
+        }
+        if (writeResult.needs_approval) {
+            if (!writeResult.diff_artifact) {
+                throw new Error(`closeLoop: writeProjectMdSafe returned needs_approval without a diff_artifact — invariant violation`);
+            }
+            if (!project_md_final_id) {
+                throw new Error(`closeLoop: writeProjectMdSafe returned needs_approval but no project_md_final artifact found on loop ${current.id}`);
+            }
+            const slot = current.slots[0];
+            if (!slot) {
+                throw new Error(`closeLoop: bootstrap loop ${current.id} has no slots — cannot synthesize operator_question for file_overwrite_approval`);
+            }
+            const pauseNow = nowISO();
+            const pauseMutationId = generateMutationId();
+            const pauseVersion = current.version + 1;
+            const eventsSoFar = listLoopEvents(input.id, cwd);
+            let pauseSeq = (eventsSoFar[eventsSoFar.length - 1]?.seq ?? 0) + 1;
+            const { artifact: questionArtifact, question_id } = buildFileOverwriteApprovalQuestion({
+                phase: current.current_phase,
+                slot_id: slot.slot_id,
+                produced_by: slot.agent_id ?? slot.agent ?? input.actor,
+                target_path: writeResult.target_path,
+                project_md_final_id,
+                now: pauseNow,
+            });
+            const pausedThread = {
+                ...current,
+                version: pauseVersion,
+                mutation_id: pauseMutationId,
+                status: 'paused',
+                pause_reason: 'awaiting_file_apply',
+                pending_file_apply: {
+                    artifact_id: project_md_final_id,
+                    target_path: writeResult.target_path,
+                    diff_artifact_id: writeResult.diff_artifact.artifact_id,
+                },
+                artifacts: [...current.artifacts, writeResult.diff_artifact, questionArtifact],
+                open_questions: [...current.open_questions, question_id],
+                updated_at: pauseNow,
+            };
+            appendEvent(current.id, {
+                event_id: crypto.randomUUID(),
+                loop_id: current.id,
+                seq: pauseSeq,
+                at: pauseNow,
+                by: input.actor,
+                mutation_id: pauseMutationId,
+                kind: 'file_apply_requested',
+                artifact_id: project_md_final_id,
+                target_path: writeResult.target_path,
+            }, cwd);
+            pauseSeq += 1;
+            appendEvent(current.id, {
+                event_id: crypto.randomUUID(),
+                loop_id: current.id,
+                seq: pauseSeq,
+                at: pauseNow,
+                by: input.actor,
+                mutation_id: pauseMutationId,
+                kind: 'input_requested',
+                question_id,
+                pause_scope: 'loop',
+                by_slot_id: slot.slot_id,
+            }, cwd, 
+            // pln#513 phase 4 codex review fix — pass the paused-thread snapshot
+            // so the notification hook reads the freshly-added file_overwrite
+            // operator_question rather than the previous on-disk thread.
+            pausedThread);
+            writeThreadFile(pausedThread, cwd);
+            throw new AwaitingFileApplyApprovalError(current.id, question_id, writeResult.target_path, writeResult.diff_artifact.artifact_id);
+        }
+        fileWritten = writeResult.written === true;
+    }
     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;
+    let seq = (events[events.length - 1]?.seq ?? 0) + 1;
+    // Emit file_apply_resolved(approved=true) BEFORE the closed event when
+    // the bootstrap hook wrote the file directly (absent/empty target). The
+    // synthetic event documents that the close went through without operator
+    // intervention so the journal reads symmetrically with the paused-then-
+    // approved branch.
+    if (runBootstrapHook && fileWritten && project_md_final_id) {
+        appendEvent(current.id, {
+            event_id: crypto.randomUUID(),
+            loop_id: current.id,
+            seq,
+            at: now,
+            by: input.actor,
+            mutation_id,
+            kind: 'file_apply_resolved',
+            artifact_id: project_md_final_id,
+            approved: true,
+        }, cwd);
+        seq += 1;
+    }
     const next = {
         ...current,
         version,
@@ -183,6 +397,12 @@ export function closeLoop(input, cwd) {
         status: input.final_status,
         updated_at: now,
         closed_at: now,
+        // pln#508 step 3 — schema invariant requires pause_reason /
+        // pending_file_apply to be absent outside status='paused'. closeLoop on
+        // a paused thread must clear both, otherwise LoopThreadSchema.parse
+        // rejects the write.
+        pause_reason: undefined,
+        pending_file_apply: undefined,
     };
     appendEvent(input.id, {
         event_id: crypto.randomUUID(),