brainclaw 1.5.5 → 1.6.0

package/dist/cli.js

@@ -105,6 +105,8 @@ import { runMigrate } from './commands/migrate.js';
 import { runRunProfile } from './commands/run-profile.js';
 import { runCompact } from './commands/compact.js';
 import { runHarvestCandidates } from './commands/harvest.js';
+import { runQuestionsCommand } from './commands/questions.js';
+import { runReplyCommand } from './commands/reply.js';
 import { requireRegisteredAgentIdentity } from './core/agent-registry.js';
 const program = new Command();
 function collect(value, previous) {
@@ -194,8 +196,10 @@ program
             logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
         }
     }
-    else if (explicitCwd) {
-        // For init/setup, still respect explicit --cwd / --project but nothing else
+    else if (explicitCwd && cmdName !== 'init') {
+        // For setup commands, still respect explicit --cwd / --project but nothing else.
+        // init receives cwd through runInit options so scaffold writers do not
+        // depend on changing process.cwd().
         process.chdir(path.resolve(explicitCwd));
     }
 });
@@ -212,8 +216,13 @@ program
     .option('--no-analyze-repo', 'Skip repository analysis when suggesting a project mode')
     .option('--no-ai-scan', 'Skip AI surface scan during init')
     .option('--scan', 'Scan subdirectories for service boundaries and suggest init targets')
+    .option('--cwd <path>', 'Override working directory for init scaffolding (parity with other CLI commands)')
     .action(async (options) => {
-    await runInit(options);
+    // pln#515 step 1: commander binds --cwd to the program-level option even
+    // when it appears after `init`, so resolve via program.opts() and feed
+    // runInit's existing options.cwd plumb.
+    const programCwd = program.opts().cwd;
+    await runInit({ ...options, cwd: options.cwd ?? programCwd });
 });
 // --- setup ---
 program
@@ -1296,8 +1305,8 @@ program
     .option('--maintenance-mode <mode>', 'Maintenance mode: full (default) or fast')
     .option('--include-context', 'Output full project context after starting session (replaces separate context call)')
     .option('--json', 'Output as JSON')
-    .action((options) => {
-    runSessionStart(options);
+    .action(async (options) => {
+    await runSessionStart(options);
 });
 // --- session-end ---
 program
@@ -1313,8 +1322,8 @@ program
     .option('--reviewer <name>', 'Explicit reviewer to route the reflected handoff review to')
     .option('--reflect', 'Include structured reflection questions for the agent to answer')
     .option('--json', 'Output as JSON')
-    .action((options) => {
-    runSessionEnd({
+    .action(async (options) => {
+    await runSessionEnd({
         ...options,
         autoReflect: options.autoReflect,
         autoRelease: options.autoRelease,
@@ -1873,6 +1882,114 @@ if (isCodevEnabled()) {
         runCodevMetrics(thread, { ...options, cwd: globalOpts.cwd });
     });
 }
+// --- questions (operator-question artifacts across loops; pln#508 step 4) ---
+program
+    .command('questions')
+    .description('List pending operator_question artifacts across loops in the current project')
+    .option('--loop <loop_id>', 'Filter to a single loop')
+    .option('--status <status>', 'Filter by status: awaiting (default), answered, timed_out', 'awaiting')
+    .option('--mine', 'Filter to questions targeted at the current agent (v1 heuristic: humans see all awaiting)')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    const globalOpts = program.opts();
+    const status = options.status;
+    if (!['awaiting', 'answered', 'timed_out'].includes(status)) {
+        console.error(`Error: --status must be one of awaiting|answered|timed_out (got "${options.status}")`);
+        process.exit(1);
+    }
+    runQuestionsCommand({
+        loop: options.loop,
+        status,
+        mine: options.mine,
+        json: options.json,
+    }, globalOpts.cwd);
+});
+// --- bootstrap-loop (open/join/status/cancel a bootstrap loop; pln#513 step 3) ---
+program
+    .command('bootstrap-loop')
+    .description('Open or join a bootstrap loop on the current project, or query its status')
+    .option('--status', 'Report current state')
+    .option('--cancel', 'Cancel the active bootstrap loop')
+    .option('--yes', 'Skip confirmation prompts')
+    .option('--json', 'Machine-readable output')
+    .action(async (options) => {
+    const globalOpts = program.opts();
+    const { runBootstrapLoopCommand } = await import('./commands/bootstrap-loop.js');
+    await runBootstrapLoopCommand(options, globalOpts.cwd);
+});
+// --- loop (drive loop turn verbs; pln#517 step 2) ---
+const loopCmd = program
+    .command('loop')
+    .description('Drive a loop turn (turn / complete-turn / advance / add-artifact)');
+loopCmd
+    .command('turn <loop_id>')
+    .description('Issue a turn assignment on a slot')
+    .requiredOption('--slot <slot_id>', 'Target slot id (lsl_...)')
+    .option('--input <text>', 'Free-form input passed to the slot')
+    .option('--role <role>', 'Slot role (resolves the first non-done slot with that role)')
+    .option('--assignment-id <id>', 'Dispatcher-provided assignment id to record on the slot')
+    .option('--json', 'Machine-readable output')
+    .action(async (loop_id, options) => {
+    const globalOpts = program.opts();
+    const { runLoopCommand } = await import('./commands/loop.js');
+    await runLoopCommand('turn', { loop_id }, options, globalOpts.cwd);
+});
+loopCmd
+    .command('complete-turn <loop_id>')
+    .description('Complete a slot turn')
+    .requiredOption('--slot <slot_id>', 'Target slot id (lsl_...)')
+    .requiredOption('--outcome <outcome>', 'Turn outcome: done, failed, or cancelled')
+    .option('--failure-reason <text>', 'Reason when outcome is failed')
+    .option('--artifact <json>', 'JSON object payload for an artifact to attach')
+    .option('--json', 'Machine-readable output')
+    .action(async (loop_id, options) => {
+    const globalOpts = program.opts();
+    const { runLoopCommand } = await import('./commands/loop.js');
+    await runLoopCommand('complete-turn', { loop_id }, options, globalOpts.cwd);
+});
+loopCmd
+    .command('advance <loop_id>')
+    .description('Advance a loop to its next phase')
+    .option('--to-phase <name>', 'Explicit target phase')
+    .option('--force', 'Bypass phase gate checks')
+    .option('--reason <text>', 'Reason to record on the phase advance event')
+    .option('--json', 'Machine-readable output')
+    .action(async (loop_id, options) => {
+    const globalOpts = program.opts();
+    const { runLoopCommand } = await import('./commands/loop.js');
+    await runLoopCommand('advance', { loop_id }, options, globalOpts.cwd);
+});
+loopCmd
+    .command('add-artifact <loop_id>')
+    .description('Attach an artifact to a loop')
+    .requiredOption('--phase <phase>', 'Artifact phase')
+    .requiredOption('--type <type>', 'Artifact type')
+    .requiredOption('--body <json-or-text>', 'Artifact body as JSON or text')
+    .option('--produced-by <agent>', 'Agent that produced the artifact')
+    .option('--ref <ref>', 'JSON ref object, e.g. {"kind":"plan","id":"pln_..."}')
+    .option('--json', 'Machine-readable output')
+    .action(async (loop_id, options) => {
+    const globalOpts = program.opts();
+    const { runLoopCommand } = await import('./commands/loop.js');
+    await runLoopCommand('add-artifact', { loop_id }, options, globalOpts.cwd);
+});
+// --- reply (provide_input to an operator_question; pln#508 step 4) ---
+program
+    .command('reply <qst_id>')
+    .description('Resolve an operator_question artifact (wraps bclaw_loop.provide_input)')
+    .option('--answer <text>', 'Free-form answer text')
+    .option('--choose <option_id>', 'Pick one of the question\'s structured options[].id')
+    .option('--skip', 'Materialize the question\'s suggested_default')
+    .option('--json', 'Output as JSON')
+    .action((qstId, options) => {
+    const globalOpts = program.opts();
+    runReplyCommand(qstId, {
+        answer: options.answer,
+        choose: options.choose,
+        skip: options.skip,
+        json: options.json,
+    }, globalOpts.cwd);
+});
 // --- run (agent profiles) ---
 program
     .command('run [profile-name]')

package/dist/commands/bootstrap-loop.js

@@ -0,0 +1,206 @@
+import readline from 'node:readline';
+import { memoryExists } from '../core/io.js';
+import { acquireBootstrapLoop, BootstrapCoordinationInProgressError, closeLoop, computeNextExpected, findExistingBootstrapLoop, } from '../core/loops/index.js';
+import { resolveCurrentAgentName } from '../core/agent-registry.js';
+function fail(message, exitCode, opts) {
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+    process.exit(exitCode);
+}
+function parseQuestionBody(artifact) {
+    if (artifact.type !== 'operator_question' || !artifact.body)
+        return undefined;
+    try {
+        return JSON.parse(artifact.body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function formatNextExpected(hint) {
+    if (!hint)
+        return '  (loop has no further expected action)';
+    const bits = [`  next: ${hint.action} (${hint.intent})`];
+    if (hint.phase)
+        bits.push(`  phase: ${hint.phase}`);
+    if (hint.slot_id)
+        bits.push(`  slot: ${hint.slot_id}${hint.role ? ` [${hint.role}]` : ''}`);
+    if (hint.from_phase && hint.to_phase)
+        bits.push(`  ${hint.from_phase} → ${hint.to_phase}`);
+    if (hint.blocking_on.length)
+        bits.push(`  blocking_on: ${hint.blocking_on.join(', ')}`);
+    if (hint.reason)
+        bits.push(`  reason: ${hint.reason}`);
+    return bits.join('\n');
+}
+function buildResult(action, loop) {
+    const hint = action === 'cancelled' ? null : computeNextExpected(loop);
+    const openQuestions = loop.open_questions;
+    const result = {
+        ok: true,
+        action,
+        loop_id: loop.id,
+        current_phase: loop.current_phase,
+        status: loop.status,
+        open_questions: openQuestions,
+        next_expected: hint,
+    };
+    if (loop.pause_reason) {
+        result.pause_reason = loop.pause_reason;
+    }
+    if (loop.pending_file_apply) {
+        result.pending_file_apply = {
+            target_path: loop.pending_file_apply.target_path,
+            artifact_id: loop.pending_file_apply.artifact_id,
+            diff_artifact_id: loop.pending_file_apply.diff_artifact_id,
+        };
+    }
+    if (action === 'joined') {
+        result.joined_existing = true;
+    }
+    return result;
+}
+function printHuman(result, loop) {
+    const prefix = result.action === 'opened'
+        ? '✔ Opened bootstrap loop'
+        : result.action === 'joined'
+            ? '↺ Joined existing bootstrap loop'
+            : result.action === 'cancelled'
+                ? '✔ Cancelled bootstrap loop'
+                : '• Bootstrap loop status';
+    console.log(`${prefix} ${loop.id}`);
+    console.log(`  phase: ${loop.current_phase}`);
+    console.log(`  status: ${loop.status}`);
+    if (result.pause_reason) {
+        console.log(`  pause_reason: ${result.pause_reason}`);
+    }
+    if (loop.open_questions.length > 0) {
+        console.log(`  open_questions: ${loop.open_questions.length} (${loop.open_questions.join(', ')})`);
+        for (const q of loop.artifacts) {
+            const body = parseQuestionBody(q);
+            if (body && loop.open_questions.includes(body.question_id)) {
+                console.log(`    - ${body.question_id}: ${body.question_text}`);
+            }
+        }
+    }
+    if (result.pending_file_apply) {
+        console.log(`  pending_file_apply: ${result.pending_file_apply.target_path}`);
+    }
+    if (loop.slots.length > 0) {
+        const slotDesc = loop.slots
+            .map((s) => `${s.role}${s.agent ? `=${s.agent}` : ''} [${s.status}]`)
+            .join(', ');
+        console.log(`  slots: ${slotDesc}`);
+    }
+    if (result.action !== 'cancelled') {
+        console.log(formatNextExpected(result.next_expected ?? null));
+    }
+}
+async function confirmCancel(loopId) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(`Cancel bootstrap loop ${loopId}? This sets status='cancelled'. [y/N] `, (a) => resolve(a));
+        });
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * `brainclaw bootstrap-loop` — open, join, query, or cancel the bootstrap
+ * loop on the current project. The open/join path delegates to
+ * `acquireBootstrapLoop` (src/core/loops/bootstrap-acquire.ts) which
+ * implements the same coordination-lock singleton acquire used by the MCP
+ * bclaw_coordinate facade. Two concurrent CLI invocations will now converge
+ * on the same loop rather than opening duplicates (pln#518 step 1).
+ */
+export async function runBootstrapLoopCommand(options = {}, cwd) {
+    if (!memoryExists(cwd)) {
+        fail('.brainclaw/ not found. Run `brainclaw init` first.', 1, options);
+    }
+    const modes = [];
+    if (options.status)
+        modes.push('--status');
+    if (options.cancel)
+        modes.push('--cancel');
+    if (modes.length > 1) {
+        fail(`--status and --cancel are mutually exclusive (got: ${modes.join(', ')})`, 1, options);
+    }
+    if (options.status) {
+        const existing = findExistingBootstrapLoop(cwd);
+        if (!existing) {
+            fail('no active bootstrap loop on this project. Run `brainclaw bootstrap-loop` to open one.', 1, options);
+        }
+        const result = buildResult('status', existing);
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        printHuman(result, existing);
+        return;
+    }
+    if (options.cancel) {
+        const existing = findExistingBootstrapLoop(cwd);
+        if (!existing) {
+            fail('no active bootstrap loop to cancel on this project.', 1, options);
+        }
+        if (!options.yes) {
+            const confirmed = await confirmCancel(existing.id);
+            if (!confirmed) {
+                fail('cancellation aborted by operator.', 1, options);
+            }
+        }
+        const actor = resolveCurrentAgentName(cwd);
+        let closed;
+        try {
+            closed = closeLoop({
+                id: existing.id,
+                final_status: 'cancelled',
+                reason: 'operator_cancelled',
+                actor,
+            }, cwd);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            fail(`closeLoop verb rejected the call: ${msg}`, 2, options);
+        }
+        const result = buildResult('cancelled', closed);
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        printHuman(result, closed);
+        return;
+    }
+    // No-args: delegate to the singleton acquire path (pln#518 step 1).
+    // acquireBootstrapLoop handles find-existing + coordination-lock + openLoop,
+    // preventing two concurrent CLI invocations from both calling openLoop.
+    const actor = resolveCurrentAgentName(cwd);
+    let loop;
+    let action;
+    try {
+        const acquired = acquireBootstrapLoop({ actor }, cwd);
+        loop = acquired.loop;
+        action = acquired.action;
+    }
+    catch (err) {
+        if (err instanceof BootstrapCoordinationInProgressError) {
+            fail(err.message, 2, options);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        fail(`bootstrap-loop acquire failed: ${msg}`, 2, options);
+    }
+    const result = buildResult(action, loop);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    printHuman(result, loop);
+}
+//# sourceMappingURL=bootstrap-loop.js.map

package/dist/commands/loop.js

@@ -0,0 +1,156 @@
+import { memoryExists } from '../core/io.js';
+import { handleBclawLoop } from './loops-handlers.js';
+function fail(message, exitCode, opts) {
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+    process.exit(exitCode);
+}
+function requireLoopId(args, opts) {
+    const loopId = args.loop_id;
+    if (!loopId || !/^lop_[0-9a-z]+$/.test(loopId)) {
+        fail(`invalid loop_id "${loopId ?? ''}" — expected format lop_<hex>`, 1, opts);
+    }
+    return loopId;
+}
+function requireOption(value, flag, opts) {
+    if (value === undefined || value === '') {
+        fail(`${flag} is required`, 1, opts);
+    }
+    return value;
+}
+function parseJsonObject(raw, flag, opts) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        fail(`${flag} must be valid JSON object syntax: ${message}`, 1, opts);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        fail(`${flag} must be a JSON object`, 1, opts);
+    }
+    return parsed;
+}
+function parseOptionalRef(raw, opts) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = parseJsonObject(raw, '--ref', opts);
+    if (typeof parsed.kind !== 'string' || typeof parsed.id !== 'string') {
+        fail('--ref must be a JSON object with string fields { "kind", "id" }', 1, opts);
+    }
+    return { kind: parsed.kind, id: parsed.id };
+}
+function parseBody(raw) {
+    try {
+        return JSON.stringify(JSON.parse(raw));
+    }
+    catch {
+        return raw;
+    }
+}
+function parseOutcome(opts) {
+    const outcome = opts.outcome;
+    if (outcome !== 'done' && outcome !== 'failed' && outcome !== 'cancelled') {
+        fail(`--outcome must be one of done|failed|cancelled (got "${outcome ?? ''}")`, 1, opts);
+    }
+    return outcome;
+}
+function formatNextExpected(hint) {
+    if (!hint)
+        return '  (loop has no further expected action)';
+    const bits = [`  next: ${hint.action} (${hint.intent})`];
+    if (hint.phase)
+        bits.push(`  phase: ${hint.phase}`);
+    if (hint.slot_id)
+        bits.push(`  slot: ${hint.slot_id}${hint.role ? ` [${hint.role}]` : ''}`);
+    if (hint.from_phase && hint.to_phase)
+        bits.push(`  ${hint.from_phase} -> ${hint.to_phase}`);
+    if (hint.blocking_on.length)
+        bits.push(`  blocking_on: ${hint.blocking_on.join(', ')}`);
+    if (hint.reason)
+        bits.push(`  reason: ${hint.reason}`);
+    return bits.join('\n');
+}
+function buildRequest(subcommand, loopId, opts) {
+    switch (subcommand) {
+        case 'turn':
+            return {
+                intent: 'turn',
+                loop_id: loopId,
+                slot_id: requireOption(opts.slot, '--slot <slot_id>', opts),
+                input: requireOption(opts.input, '--input <text>', opts),
+                role: opts.role,
+                assignment_id: opts.assignmentId,
+            };
+        case 'complete-turn': {
+            const artifact = opts.artifact
+                ? parseJsonObject(opts.artifact, '--artifact', opts)
+                : undefined;
+            return {
+                intent: 'complete_turn',
+                loop_id: loopId,
+                slot_id: requireOption(opts.slot, '--slot <slot_id>', opts),
+                outcome: parseOutcome(opts),
+                failure_reason: opts.failureReason,
+                artifact,
+            };
+        }
+        case 'advance':
+            return {
+                intent: 'advance',
+                loop_id: loopId,
+                to_phase: opts.toPhase,
+                force: opts.force,
+                reason: opts.reason,
+            };
+        case 'add-artifact':
+            return {
+                intent: 'add_artifact',
+                loop_id: loopId,
+                artifact: {
+                    phase: requireOption(opts.phase, '--phase <phase>', opts),
+                    type: requireOption(opts.type, '--type <type>', opts),
+                    body: parseBody(requireOption(opts.body, '--body <json-or-text>', opts)),
+                    produced_by: opts.producedBy,
+                    ref: parseOptionalRef(opts.ref, opts),
+                },
+            };
+    }
+}
+export function runLoopCommand(subcommand, args, options = {}, cwd) {
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const loopId = requireLoopId(args, options);
+    const request = buildRequest(subcommand, loopId, options);
+    const handled = handleBclawLoop({ args: request, cwd });
+    if (handled.response.status !== 'ok') {
+        const message = handled.response.error ?? handled.summary;
+        fail(`bclaw_loop.${String(request.intent)} rejected the call: ${message}`, 2, options);
+    }
+    const result = handled.response.result;
+    const loop = result.loop;
+    const out = {
+        ok: true,
+        action: subcommand,
+        loop_id: loop?.id ?? loopId,
+        current_phase: loop?.current_phase,
+        status: loop?.status,
+        next_expected: result.next_expected ?? null,
+        auto_closed: result.auto_closed || undefined,
+    };
+    if (options.json) {
+        console.log(JSON.stringify(out, null, 2));
+        return out;
+    }
+    console.log(`OK loop ${subcommand} ${out.loop_id}${out.current_phase ? ` phase=${out.current_phase}` : ''}${out.status ? ` status=${out.status}` : ''}`);
+    console.log(formatNextExpected(out.next_expected));
+    return out;
+}
+//# sourceMappingURL=loop.js.map