brainclaw 1.5.5 → 1.6.0

package/dist/core/loops/hooks/notify-operator.js

@@ -0,0 +1,148 @@
+import child_process from 'node:child_process';
+/**
+ * pln#513 step 4 — OS notifications hook on input_requested events.
+ *
+ * Best-effort, fire-and-forget OS-native heads-up so the operator notices
+ * when a bootstrap loop pauses on an operator_question. Gated by
+ * `BRAINCLAW_OPERATOR_NOTIFICATIONS=1` (opt-in) and scoped to bootstrap-preset
+ * loops in v1. Every code path is wrapped so a missing notifier binary,
+ * unparseable artifact body, or spawn error never propagates to the caller —
+ * the journal write must remain the source of truth.
+ */
+const TITLE = 'brainclaw';
+const QUESTION_TEXT_CAP = 80;
+function isEnabled() {
+    return process.env.BRAINCLAW_OPERATOR_NOTIFICATIONS === '1';
+}
+function isBootstrapLoop(loop) {
+    return loop.protocol?.preset === 'bootstrap';
+}
+/**
+ * Resolve the matching operator_question artifact body for the event's
+ * question_id and return its question_text, truncated. Returns undefined
+ * whenever the artifact can't be located or its body fails to parse —
+ * the notification body still works without it.
+ */
+function resolveQuestionText(event, loop) {
+    if (event.kind !== 'input_requested')
+        return undefined;
+    for (const artifact of loop.artifacts) {
+        if (artifact.type !== 'operator_question' || artifact.body === undefined)
+            continue;
+        try {
+            const body = JSON.parse(artifact.body);
+            if (body.question_id === event.question_id) {
+                const text = body.question_text;
+                if (typeof text !== 'string' || text.length === 0)
+                    return undefined;
+                return text.length > QUESTION_TEXT_CAP
+                    ? `${text.slice(0, QUESTION_TEXT_CAP)}…`
+                    : text;
+            }
+        }
+        catch {
+            // ignore unparseable bodies; fall through to the next artifact
+        }
+    }
+    return undefined;
+}
+/**
+ * Sanitize the message before passing it to a shell-bridge command
+ * (osascript, powershell). We allow only printable ASCII apart from
+ * double-quotes / backticks / backslashes / control chars to avoid quoting
+ * pitfalls on every platform. The fallback `notify-send` on Linux runs
+ * via an arg vector so its sanitization is just length-capping.
+ */
+function sanitizeForShell(message) {
+    return message
+        .replace(/["`\\$]/g, '')
+        .replace(/[\r\n\t]/g, ' ')
+        .replace(/[\x00-\x1f\x7f]/g, '');
+}
+function composeMessage(event, loop) {
+    const base = `brainclaw bootstrap: question awaiting input on loop ${loop.id}`;
+    const text = resolveQuestionText(event, loop);
+    return text ? `${base} — ${text}` : base;
+}
+function spawnDetached(command, args) {
+    const child = child_process.spawn(command, args, {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.on('error', () => {
+        // missing binary or exec failure — best-effort, swallow.
+    });
+    child.unref();
+}
+function notifyLinux(message) {
+    spawnDetached('notify-send', [TITLE, message]);
+}
+function notifyMac(message) {
+    const safe = sanitizeForShell(message);
+    spawnDetached('osascript', [
+        '-e',
+        `display notification "${safe}" with title "${TITLE}"`,
+    ]);
+}
+function notifyWindows(message) {
+    const safe = sanitizeForShell(message);
+    // Try BurntToast if available; fall back to a terminal bell on stderr if
+    // PowerShell itself cannot be invoked. Both paths are best-effort — we
+    // never observe the exit code.
+    const psCommand = `if (Get-Module -ListAvailable -Name BurntToast) { ` +
+        `Import-Module BurntToast; New-BurntToastNotification -Text "${TITLE}", "${safe}" ` +
+        `} else { [console]::Beep(800, 200) }`;
+    const child = child_process.spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', psCommand], { detached: true, stdio: 'ignore', windowsHide: true });
+    child.on('error', () => {
+        try {
+            process.stderr.write('\x07');
+        }
+        catch {
+            // give up silently
+        }
+    });
+    child.unref();
+}
+/**
+ * Fire an OS-native notification on `input_requested` events for bootstrap
+ * loops. Returns immediately when:
+ *   - the event is not `input_requested`,
+ *   - the env-var opt-in is missing,
+ *   - the loop's protocol preset is not `bootstrap`,
+ *   - the host platform has no supported notifier.
+ *
+ * Never throws. The cwd parameter is accepted for parity with other hooks
+ * but currently unused — the hook decides everything from the event + loop
+ * snapshot the caller already loaded.
+ */
+export function notifyOperatorOnInputRequested(event, loop, cwd) {
+    void cwd;
+    try {
+        if (event.kind !== 'input_requested')
+            return;
+        if (!isEnabled())
+            return;
+        if (!isBootstrapLoop(loop))
+            return;
+        const message = composeMessage(event, loop);
+        switch (process.platform) {
+            case 'linux':
+                notifyLinux(message);
+                return;
+            case 'darwin':
+                notifyMac(message);
+                return;
+            case 'win32':
+                notifyWindows(message);
+                return;
+            default:
+                return;
+        }
+    }
+    catch {
+        // Hook is best-effort — swallow any unexpected error so the journal
+        // write that triggered us stays the source of truth.
+    }
+}
+//# sourceMappingURL=notify-operator.js.map

package/dist/core/loops/hooks/survey-source-reader.js

@@ -0,0 +1,256 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULT_MAX_BYTES = 50 * 1024;
+const MAX_INDIVIDUAL_FILE_BYTES = 1024 * 1024;
+export function readSurveySources(cwd, opts) {
+    const cap = opts?.maxBytes ?? DEFAULT_MAX_BYTES;
+    const log = [];
+    const result = {
+        excerpts: [],
+        total_byte_count: 0,
+        cap_exceeded: false,
+        cap_bytes: cap,
+        reasoning_log: log,
+    };
+    let rootEntries;
+    try {
+        rootEntries = fs.readdirSync(cwd, { withFileTypes: true });
+    }
+    catch (err) {
+        log.push(`could not read project root: ${err.message}`);
+        return result;
+    }
+    const readmeFiles = [];
+    const licenseFiles = [];
+    for (const entry of rootEntries) {
+        if (!entry.isFile())
+            continue;
+        const upper = entry.name.toUpperCase();
+        if (/^README.*\.MD$/.test(upper)) {
+            readmeFiles.push(entry.name);
+        }
+        else if (/^LICENSE(\.MD|\.TXT)?$/.test(upper)) {
+            licenseFiles.push(entry.name);
+        }
+    }
+    readmeFiles.sort();
+    licenseFiles.sort();
+    const candidates = [...readmeFiles, ...licenseFiles];
+    const entryPoint = detectEntryPoint(cwd, rootEntries, log);
+    if (entryPoint) {
+        if (!candidates.includes(entryPoint))
+            candidates.push(entryPoint);
+    }
+    else {
+        log.push('no manifest-referenced entry point found');
+    }
+    for (const relPath of candidates) {
+        const absPath = path.join(cwd, relPath);
+        let stat;
+        try {
+            stat = fs.statSync(absPath);
+        }
+        catch (err) {
+            log.push(`skipped ${relPath}: ${err.message}`);
+            continue;
+        }
+        if (!stat.isFile()) {
+            log.push(`skipped ${relPath}: not a regular file`);
+            continue;
+        }
+        if (stat.size > MAX_INDIVIDUAL_FILE_BYTES) {
+            log.push(`skipped ${relPath}: size ${stat.size} bytes exceeds 1MB individual safety cap`);
+            result.cap_exceeded = true;
+            continue;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(absPath, 'utf8');
+        }
+        catch (err) {
+            log.push(`skipped ${relPath}: UTF-8 read failed (${err.message})`);
+            continue;
+        }
+        const remaining = cap - result.total_byte_count;
+        if (remaining <= 0) {
+            log.push(`skipped ${relPath}: cap of ${cap} bytes already reached`);
+            result.cap_exceeded = true;
+            break;
+        }
+        const normalized = relPath.replace(/\\/g, '/');
+        const fileBytes = Buffer.byteLength(content, 'utf8');
+        if (fileBytes <= remaining) {
+            result.excerpts.push({
+                file: normalized,
+                byte_count: fileBytes,
+                body_truncated: false,
+                body: content,
+            });
+            result.total_byte_count += fileBytes;
+            log.push(`included ${normalized} (${fileBytes} bytes)`);
+        }
+        else {
+            const truncated = truncateToBytes(content, remaining);
+            const truncatedBytes = Buffer.byteLength(truncated, 'utf8');
+            result.excerpts.push({
+                file: normalized,
+                byte_count: truncatedBytes,
+                body_truncated: true,
+                body: truncated,
+            });
+            result.total_byte_count += truncatedBytes;
+            result.cap_exceeded = true;
+            log.push(`truncated ${normalized} from ${fileBytes} to ${truncatedBytes} bytes to fit cap of ${cap}`);
+            break;
+        }
+    }
+    return result;
+}
+function truncateToBytes(s, maxBytes) {
+    const buf = Buffer.from(s, 'utf8');
+    if (buf.length <= maxBytes)
+        return s;
+    let end = maxBytes;
+    while (end > 0 && (buf[end] & 0xc0) === 0x80)
+        end--;
+    return buf.subarray(0, end).toString('utf8');
+}
+function detectEntryPoint(cwd, rootEntries, log) {
+    const fileNames = new Set();
+    for (const entry of rootEntries) {
+        if (entry.isFile())
+            fileNames.add(entry.name);
+    }
+    for (const name of fileNames) {
+        if (name.endsWith('.spec')) {
+            const found = parsePyinstallerSpec(path.join(cwd, name), log);
+            if (found)
+                return found;
+        }
+    }
+    if (fileNames.has('package.json')) {
+        const found = parsePackageJson(path.join(cwd, 'package.json'), log);
+        if (found)
+            return found;
+    }
+    if (fileNames.has('pyproject.toml')) {
+        const found = parsePyproject(path.join(cwd, 'pyproject.toml'), log);
+        if (found)
+            return found;
+    }
+    if (fileNames.has('Cargo.toml')) {
+        const found = parseCargoToml(path.join(cwd, 'Cargo.toml'), cwd, log);
+        if (found)
+            return found;
+    }
+    if (fileNames.has('go.mod')) {
+        if (fileNames.has('main.go'))
+            return 'main.go';
+        const found = findGoCmdMain(cwd);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function parsePyinstallerSpec(file, log) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        log.push(`pyinstaller .spec read failed: ${err.message}`);
+        return undefined;
+    }
+    const m = /Analysis\(\s*\[\s*['"]([^'"]+)['"]/.exec(text);
+    return m ? m[1] : undefined;
+}
+function parsePackageJson(file, log) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        log.push(`package.json parse failed: ${err.message}`);
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const obj = parsed;
+    if (typeof obj.main === 'string')
+        return obj.main;
+    if (typeof obj.bin === 'string')
+        return obj.bin;
+    if (obj.bin && typeof obj.bin === 'object') {
+        for (const v of Object.values(obj.bin)) {
+            if (typeof v === 'string')
+                return v;
+        }
+    }
+    return undefined;
+}
+function parsePyproject(file, log) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        log.push(`pyproject.toml read failed: ${err.message}`);
+        return undefined;
+    }
+    for (const header of ['[project.scripts]', '[tool.poetry.scripts]']) {
+        const idx = text.indexOf(header);
+        if (idx === -1)
+            continue;
+        const rest = text.slice(idx + header.length);
+        const nextSectionRel = rest.search(/\n\s*\[/);
+        const section = nextSectionRel >= 0 ? rest.slice(0, nextSectionRel) : rest;
+        for (const line of section.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const m = /^[A-Za-z_][\w-]*\s*=\s*['"]([^'"]+)['"]/.exec(trimmed);
+            if (m)
+                return moduleSpecToPath(m[1]);
+        }
+    }
+    return undefined;
+}
+function moduleSpecToPath(spec) {
+    const modulePart = spec.split(':')[0];
+    return modulePart.split('.').join('/') + '.py';
+}
+function parseCargoToml(file, cwd, log) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        log.push(`Cargo.toml read failed: ${err.message}`);
+        return undefined;
+    }
+    const binMatch = /\[\[bin\]\][\s\S]*?path\s*=\s*['"]([^'"]+)['"]/.exec(text);
+    if (binMatch)
+        return binMatch[1];
+    if (fs.existsSync(path.join(cwd, 'src', 'main.rs')))
+        return 'src/main.rs';
+    return undefined;
+}
+function findGoCmdMain(cwd) {
+    const cmdDir = path.join(cwd, 'cmd');
+    let entries;
+    try {
+        entries = fs.readdirSync(cmdDir, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = path.join(cmdDir, entry.name, 'main.go');
+        if (fs.existsSync(candidate))
+            return path.posix.join('cmd', entry.name, 'main.go');
+    }
+    return undefined;
+}
+//# sourceMappingURL=survey-source-reader.js.map

package/dist/core/loops/index.js

@@ -1,7 +1,13 @@
 export * from './types.js';
-export { closeLoop, ensureLoopsDir, generateLoopId, generateMutationId, generateSlotId, getLoop, listLoopEvents, listLoops, openLoop, } from './store.js';
-export { add_artifact, advance, complete_turn, evaluatePhaseAdvanceGate, evaluateStopCondition, pause, resume, turn, } from './verbs.js';
+export { AwaitingFileApplyApprovalError, closeLoop, ensureLoopsDir, generateLoopId, generateMutationId, generateSlotId, getLoop, listLoopEvents, listLoops, openLoop, writeThreadFile, } from './store.js';
+export { add_artifact, advance, complete_turn, evaluatePhaseAdvanceGate, evaluateStopCondition, pause, provideInput, reconcileOpenQuestions, requestInput, resume, sweepPauseTimeouts, turn, } from './verbs.js';
 export { decideNextPhase, artifactsInIteration, noNewCritiqueInIteration, hasCriticSignalInIteration, } from './iteration-engine.js';
+export { computeNextExpected, } from './next-expected.js';
 export { buildIdeationBrief, } from './brief-assembly.js';
+export { BOOTSTRAP_PRESET } from './presets/bootstrap.js';
+export { writeProjectMdSafe, } from './hooks/bootstrap-write.js';
+export { notifyOperatorOnInputRequested } from './hooks/notify-operator.js';
+export { readSurveySources, } from './hooks/survey-source-reader.js';
 export { acquireLock, hashRequest, recordConflict, withLoopLock, DEFAULT_MAX_MUTATION_DURATION_MS, IDEMPOTENCY_TTL_MS, LEASE_GRACE_MS, LEASE_WINDOW_MS, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, LockLostError, LockTimeoutError, VersionConflictError, } from './lock.js';
+export { acquireBootstrapLoop, findExistingBootstrapLoop, BootstrapCoordinationInProgressError, } from './bootstrap-acquire.js';
 //# sourceMappingURL=index.js.map

package/dist/core/loops/next-expected.js

@@ -0,0 +1,63 @@
+export function computeNextExpected(loop) {
+    if (loop.status === 'completed' || loop.status === 'cancelled' || loop.status === 'blocked') {
+        return null;
+    }
+    // pln#508 step 3 fix from codex review (loop-handlers.ts:252): paused
+    // loops with open operator_questions should hint provide_input, not
+    // advance/close. open_questions check fires regardless of status so it
+    // also catches the slot-scope case where loop.status === 'open' but a
+    // slot is in waiting_input.
+    if (loop.open_questions.length > 0) {
+        return {
+            action: 'provide_input',
+            intent: 'bclaw_loop.provide_input',
+            reason: loop.status === 'paused' ? loop.pause_reason : 'awaiting_operator',
+            blocking_on: [...loop.open_questions],
+        };
+    }
+    if (loop.status === 'paused') {
+        return null;
+    }
+    const currentPhaseSlots = loop.slots.filter((s) => (s.phase ?? loop.current_phase) === loop.current_phase);
+    const openSlots = currentPhaseSlots.filter((s) => s.status === 'open');
+    if (openSlots.length > 0) {
+        const first = openSlots[0];
+        return {
+            action: 'turn',
+            intent: 'bclaw_loop.turn',
+            phase: loop.current_phase,
+            slot_id: first.slot_id,
+            role: first.role,
+            blocking_on: openSlots.map((s) => s.slot_id),
+        };
+    }
+    const assignedOrWorking = currentPhaseSlots.filter((s) => s.status === 'assigned' || s.status === 'working');
+    if (assignedOrWorking.length > 0) {
+        return {
+            action: 'complete_turn',
+            intent: 'bclaw_loop.complete_turn',
+            phase: loop.current_phase,
+            slot_id: assignedOrWorking[0].slot_id,
+            role: assignedOrWorking[0].role,
+            blocking_on: assignedOrWorking.map((s) => s.slot_id),
+        };
+    }
+    const phaseNames = loop.phases.map((p) => p.name);
+    const currentIndex = phaseNames.indexOf(loop.current_phase);
+    if (currentIndex >= 0 && currentIndex + 1 < phaseNames.length) {
+        return {
+            action: 'advance',
+            intent: 'bclaw_loop.advance',
+            from_phase: loop.current_phase,
+            to_phase: phaseNames[currentIndex + 1],
+            blocking_on: [],
+        };
+    }
+    return {
+        action: 'close',
+        intent: 'bclaw_loop.close',
+        reason: 'terminal_phase_reached',
+        blocking_on: [],
+    };
+}
+//# sourceMappingURL=next-expected.js.map

package/dist/core/loops/presets/bootstrap.js

@@ -0,0 +1,75 @@
+/**
+ * pln#511 step 1 — bootstrap preset.
+ *
+ * Phase chain (Phase 0 spec):
+ *   survey      → produce signals_report from existing project memory.
+ *   propose     → first-draft PROJECT.md from survey + freeform context.
+ *   clarify     → at most one round of operator questions; advance once
+ *                  open_questions drains OR the cap fires.
+ *   review_draft→ wait for the operator's verdict / answers.
+ *   converge    → emit the final project_md_final and close.
+ *
+ * `max_operator_questions=3` and `max_pause_duration='P7D'` match the
+ * Phase 0 spec defaults (mitigates feedback_agent_autonomy_gap.md — agents
+ * must not defer everything to the human).
+ */
+export const BOOTSTRAP_PRESET = {
+    phases: [
+        // pln#516 step 1 — survey reads source. The bootstrap champion SHOULD
+        // call `readSurveySources(cwd)` (exported from ../hooks/survey-source-reader.js)
+        // to populate the source_excerpts portion of its signals_report. The engine
+        // does NOT invoke this automatically; the champion drives it (RefBasedArtifactBody
+        // is unchanged — see types.ts). Empirical motivation: TranslaVox cold-start
+        // missed the actual GCP Speech+Translate pipeline because survey scanned only
+        // topology + manifests (can_0160d6c4).
+        {
+            name: 'survey',
+            context_filter: ['project_vision', 'decisions', 'plans', 'feedback'],
+            advance_gate: { kind: 'artifact_produced', phase: 'survey', type: 'signals_report' },
+        },
+        {
+            name: 'propose',
+            context_filter: ['*'],
+            advance_gate: { kind: 'artifact_produced', phase: 'propose', type: 'project_md_draft' },
+        },
+        {
+            name: 'clarify',
+            context_filter: ['critique_history', 'runtime_notes', 'feedback'],
+            // pln#516 step 2 — wrap the original `any` exit condition under a
+            // `min_iterations >= 1` floor so the gate refuses to auto-traverse at
+            // entry. Without the floor `no_open_questions` is trivially true while
+            // `open_questions` is still `[]` (it only fills once the champion calls
+            // requestInput), and `advance(propose→clarify)` slid straight into
+            // review_draft (can_d5a41770, run_4b0500c6).
+            advance_gate: {
+                kind: 'all',
+                conditions: [
+                    { kind: 'min_iterations', n: 1 },
+                    {
+                        kind: 'any',
+                        conditions: [
+                            { kind: 'no_open_questions' },
+                            { kind: 'max_iterations', n: 1 },
+                        ],
+                    },
+                ],
+            },
+        },
+        {
+            name: 'review_draft',
+            context_filter: ['*'],
+            advance_gate: { kind: 'artifact_produced', phase: 'review_draft', type: 'operator_answer' },
+        },
+        {
+            name: 'converge',
+            context_filter: ['*'],
+        },
+    ],
+    stop_condition: { kind: 'artifact_produced', phase: 'converge', type: 'project_md_final' },
+    protocol: {
+        preset: 'bootstrap',
+        max_operator_questions: 3,
+        max_pause_duration: 'P7D',
+    },
+};
+//# sourceMappingURL=bootstrap.js.map

package/dist/core/loops/presets/index.js

@@ -0,0 +1,16 @@
+import { BOOTSTRAP_PRESET } from './bootstrap.js';
+/**
+ * pln#511 step 2 — loop preset registry.
+ *
+ * The bclaw_coordinate(intent='ideate') handler resolves a caller-supplied
+ * `preset` string against this map. Adding a new preset is a one-line
+ * change here (plus the preset module itself). The handler intentionally
+ * does not import individual presets — only this registry — so unknown
+ * names produce a deterministic `unknown_preset` error referencing the
+ * keys exported from this file.
+ */
+export const PRESETS = Object.freeze({
+    bootstrap: BOOTSTRAP_PRESET,
+});
+export { BOOTSTRAP_PRESET };
+//# sourceMappingURL=index.js.map