@navels/neal 0.1.0

package/dist/neal/commands/interactive-activity.js

@@ -0,0 +1,57 @@
+import { Writable } from 'node:stream';
+import { ActivityFooter } from '../activity-footer.js';
+import { clearDiagnosticFooter, configureDiagnosticFooter, resetDiagnosticDetailState, setDiagnosticDetailContext, writeNarrative, } from '../diagnostic.js';
+import { createInteractiveKeyController } from '../interactive-controls.js';
+export async function withInteractiveActivity(options, action) {
+    let detailContext = {};
+    resetDiagnosticDetailState(detailContext);
+    const footer = new ActivityFooter();
+    configureDiagnosticFooter(footer);
+    let state = {
+        mode: options.mode,
+        activity: options.initialActivity,
+        status: options.status ?? 'running',
+        subject: options.subject,
+        startedAt: Date.now(),
+    };
+    footer.setState(state);
+    const controller = createInteractiveKeyController({
+        allowStopRequest: false,
+        getDetailFilter() {
+            return detailContext;
+        },
+    });
+    const reportActivity = async (update) => {
+        detailContext = update.detailContext ?? detailContext;
+        setDiagnosticDetailContext(detailContext);
+        state = {
+            ...state,
+            activity: update.activity,
+            status: update.status ?? state.status,
+            subject: update.subject === undefined ? state.subject : update.subject,
+        };
+        footer.setState(state);
+    };
+    try {
+        if (process.stdin.isTTY) {
+            writeNarrative('[neal] keys: v show/hide details\n');
+        }
+        return await action({
+            stderr: createNarrativeWritable(),
+            reportActivity,
+        });
+    }
+    finally {
+        controller.cleanup();
+        clearDiagnosticFooter();
+        resetDiagnosticDetailState();
+    }
+}
+function createNarrativeWritable() {
+    return new Writable({
+        write(chunk, _encoding, callback) {
+            writeNarrative(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk);
+            callback();
+        },
+    });
+}

package/dist/neal/commands/new-run.js

@@ -0,0 +1,79 @@
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { parseNewRunArgs } from '../cli.js';
+import { assertWriterProvidersConfigured, getConfiguredUnattended } from '../config.js';
+import { assertGitRepositoryWithCommit } from '../git.js';
+import { loadOrInitialize } from '../orchestrator.js';
+import { assertAgentConfigSupportsWriterRun } from '../providers/registry.js';
+import { executeRun, withPreparedWriterRun } from './runtime.js';
+import { getExecuteRunResultExitCode, setWriterCommandExitCode } from './writer-exit-codes.js';
+const PARSE_ONLY_AGENT_CONFIG = {
+    planner: {
+        provider: 'openai-codex',
+        model: null,
+    },
+    coder: {
+        provider: 'openai-codex',
+        model: null,
+    },
+    reviewer: {
+        provider: 'anthropic-claude',
+        model: null,
+    },
+};
+export async function runNewRunCommand(args) {
+    const parsedArgs = parseNewRunArgs(args, PARSE_ONLY_AGENT_CONFIG);
+    const cwd = process.cwd();
+    const agentConfig = assertWriterProvidersConfigured(cwd, {
+        context: `new ${parsedArgs.topLevelMode} writer run`,
+    });
+    const parsed = {
+        ...parsedArgs,
+        agentConfig,
+    };
+    assertAgentConfigSupportsWriterRun(parsed.agentConfig, { context: `new ${parsed.topLevelMode} writer run` });
+    const planDoc = resolve(cwd, parsed.planDoc);
+    // Flag overrides config: `--unattended` forces true, otherwise fall back to
+    // the resolved `agent.unattended` config value (default false).
+    const unattended = parsed.unattended || getConfiguredUnattended(cwd);
+    await assertGitRepositoryWithCommit(cwd, `neal ${parsed.topLevelMode}`);
+    await requireExistingPlanFile(planDoc, parsed.planDoc);
+    const result = await withPreparedWriterRun({
+        cwd,
+        topLevelMode: parsed.topLevelMode,
+        getLockPlanDoc: () => planDoc,
+    }, async (prepared, markInitialized) => {
+        const loaded = await loadOrInitialize(planDoc, cwd, parsed.agentConfig, undefined, parsed.topLevelMode, {
+            allowedDirtyPaths: parsed.topLevelMode === 'execute' ? [planDoc] : [],
+            runDir: prepared.runDir,
+            unattended,
+            autoSquashOnCompletion: parsed.squashOnCompletion,
+        });
+        markInitialized();
+        assertAgentConfigSupportsWriterRun(loaded.state.agentConfig, { context: `new ${loaded.state.topLevelMode} writer run` });
+        return executeRun(loaded.state, loaded.statePath, loaded.logger, {
+            // The `--no-squash` flag only seeds the run state; once persisted, the
+            // state is the single source of truth so `neal resume` sees the same
+            // preference this process does.
+            autoSquashOnCompletion: loaded.state.autoSquashOnCompletion,
+            unattended,
+        });
+    });
+    setWriterCommandExitCode(getExecuteRunResultExitCode(result));
+}
+async function requireExistingPlanFile(planDoc, displayPath) {
+    let planStat;
+    try {
+        planStat = await stat(planDoc);
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            throw new Error(`Plan file does not exist: ${displayPath}`);
+        }
+        throw error;
+    }
+    if (!planStat.isFile()) {
+        throw new Error(`Plan path is not a file: ${displayPath}`);
+    }
+}

package/dist/neal/commands/plan-and-execute.js

@@ -0,0 +1,44 @@
+import process from 'node:process';
+import { parsePlanAndExecuteArgs } from '../cli.js';
+import { assertWriterProvidersConfigured, getConfiguredUnattended } from '../config.js';
+import { assertGitRepositoryWithCommit } from '../git.js';
+import { runPlanAndExecuteQueue } from '../plan-queue.js';
+import { assertAgentConfigSupportsWriterRun } from '../providers/registry.js';
+import { getPlanAndExecuteQueueExitCode, setWriterCommandExitCode } from './writer-exit-codes.js';
+const PARSE_ONLY_AGENT_CONFIG = {
+    planner: {
+        provider: 'openai-codex',
+        model: null,
+    },
+    coder: {
+        provider: 'openai-codex',
+        model: null,
+    },
+    reviewer: {
+        provider: 'anthropic-claude',
+        model: null,
+    },
+};
+export async function runPlanAndExecuteCommand(args, deps) {
+    const parsedArgs = parsePlanAndExecuteArgs(args, PARSE_ONLY_AGENT_CONFIG);
+    const cwd = process.cwd();
+    const agentConfig = assertWriterProvidersConfigured(cwd, { context: 'plan-and-execute queue' });
+    const parsed = {
+        ...parsedArgs,
+        agentConfig,
+    };
+    assertAgentConfigSupportsWriterRun(parsed.agentConfig, { context: 'plan-and-execute queue' });
+    await assertGitRepositoryWithCommit(cwd, 'neal run');
+    // Flag overrides config: `--unattended` forces true, otherwise fall back to
+    // the resolved `agent.unattended` config value (default false).
+    const unattended = parsed.unattended || getConfiguredUnattended(cwd);
+    const queueState = await runPlanAndExecuteQueue({
+        cwd,
+        planDocs: parsed.planDocs,
+        agentConfig: parsed.agentConfig,
+        squashOnCompletion: parsed.squashOnCompletion,
+        unattended,
+        deps,
+    });
+    setWriterCommandExitCode(getPlanAndExecuteQueueExitCode(queueState));
+}

package/dist/neal/commands/recovery-guidance.js

@@ -0,0 +1,217 @@
+import { basename } from 'node:path';
+import { RunLogger } from '../logger.js';
+import { InteractiveBlockedRecoveryPendingTurnError, recordInteractiveBlockedRecoveryGuidance, } from '../orchestrator/phases/recovery.js';
+import { writeExecutionArtifacts } from '../orchestrator/artifacts.js';
+import { assertAgentConfigSupportsResume } from '../providers/registry.js';
+import { formatPublicPhase } from '../phase-display.js';
+import { logUserGuidanceApplied } from '../prompts/guidance.js';
+import { decideResumeAction } from '../resume-decision.js';
+import { loadState, saveState } from '../state.js';
+function getSelectedRunId(state, selectedRunId) {
+    return selectedRunId && selectedRunId !== 'latest' ? selectedRunId : basename(state.runDir);
+}
+function getResumeCommand(state, target) {
+    return `neal resume --run ${getSelectedRunId(state, target.selectedRunId)}`;
+}
+function getUnsupportedModeMessage(state) {
+    return `neal resume --message is only supported for execute-mode recovery or blocked plan review; selected run is ${state.topLevelMode}-mode`;
+}
+function describeGuidanceStateProblem(state, target) {
+    if (state.phase === 'interactive_blocked_recovery' && !state.interactiveBlockedRecovery) {
+        return [
+            'neal resume --message cannot record guidance because the selected run is waiting for recovery guidance but has no blocked-recovery state.',
+            `Run id: ${getSelectedRunId(state, target.selectedRunId)}`,
+            `State path: ${target.statePath}`,
+        ].join('\n');
+    }
+    return [
+        'neal resume --message can record guidance only while the selected run is waiting in interactive blocked recovery.',
+        `Run id: ${getSelectedRunId(state, target.selectedRunId)}`,
+        `Current step: ${formatPublicPhase(state.phase)}`,
+        `Status: ${state.status}`,
+        `State path: ${target.statePath}`,
+    ].join('\n');
+}
+function describePlanReviewGuidanceStateProblem(state, target) {
+    return [
+        'neal resume --message can record plan-review guidance only while a top-level plan run is blocked from reviewer_plan with no pending guidance.',
+        `Run id: ${getSelectedRunId(state, target.selectedRunId)}`,
+        `Current step: ${formatPublicPhase(state.phase)}`,
+        `Status: ${state.status}`,
+        `Blocked from: ${state.blockedFromPhase ?? 'none'}`,
+        `State path: ${target.statePath}`,
+    ].join('\n');
+}
+function getPendingRecoveryTurn(state) {
+    const recovery = state.interactiveBlockedRecovery;
+    if (!recovery) {
+        return 0;
+    }
+    if (recovery.pendingDirective) {
+        return recovery.turns.length + 1;
+    }
+    return recovery.turns.find((turn) => turn.number > recovery.lastHandledTurn)?.number ?? recovery.turns.length;
+}
+function formatGuidanceDecisionRejection(decision) {
+    switch (decision.kind) {
+        case 'continue':
+            return `Run does not need --message. Resume it with: ${decision.resumeCommand}`;
+        case 'already_running':
+            return `${decision.reason}\nInspect status with: ${decision.statusCommand}`;
+        case 'done':
+            return decision.retrospectivePath
+                ? `${decision.summary}\nReview latest retrospective: ${decision.retrospectivePath}`
+                : `${decision.summary}\nInspect status with: ${decision.statusCommand}`;
+        case 'cannot_resume':
+            return `${decision.reason}\nInspect status and artifacts with: ${decision.statusCommand}`;
+    }
+}
+function isEligiblePlanReviewGuidanceState(state) {
+    return (state.topLevelMode === 'plan' &&
+        state.status === 'blocked' &&
+        state.phase === 'blocked' &&
+        state.blockedFromPhase === 'reviewer_plan' &&
+        state.pendingPlanReviewGuidance === null);
+}
+async function recordPlanReviewGuidance(args) {
+    const resumeCommand = getResumeCommand(args.state, args.target);
+    if (args.decision.kind === 'pending_message') {
+        return {
+            kind: 'pending',
+            guidanceKind: 'plan_review',
+            statePath: args.target.statePath,
+            runDir: args.state.runDir,
+            message: args.decision.reason,
+            pendingTurn: null,
+            recoveryTurns: args.state.interactiveBlockedRecovery?.turns.length ?? 0,
+            resumeCommand,
+        };
+    }
+    if (args.decision.kind !== 'needs_message') {
+        throw new Error(formatGuidanceDecisionRejection(args.decision));
+    }
+    const trimmedGuidance = args.message.trim();
+    if (!trimmedGuidance) {
+        throw new Error('Plan review guidance must not be empty');
+    }
+    if (!isEligiblePlanReviewGuidanceState(args.state)) {
+        throw new Error(describePlanReviewGuidanceStateProblem(args.state, args.target));
+    }
+    assertAgentConfigSupportsResume(args.state.agentConfig, args.state, {
+        context: 'record plan-review guidance for resume',
+    });
+    const logger = new RunLogger(args.state.runDir);
+    await logger.event('run.resumed', {
+        statePath: args.target.statePath,
+        phase: args.state.phase,
+        status: args.state.status,
+        agentConfig: args.state.agentConfig,
+    });
+    await logUserGuidanceApplied(logger);
+    const nextState = await saveState(args.target.statePath, {
+        ...args.state,
+        phase: 'coder_plan_response',
+        status: 'running',
+        blockedFromPhase: null,
+        pendingPlanReviewGuidance: {
+            message: trimmedGuidance,
+            sourcePhase: 'reviewer_plan',
+            recordedAt: new Date().toISOString(),
+        },
+    });
+    await writeExecutionArtifacts(nextState);
+    await logger.event('plan_review_guidance.recorded', {
+        statePath: args.target.statePath,
+        sourcePhase: 'reviewer_plan',
+        guidanceBytes: Buffer.byteLength(trimmedGuidance, 'utf8'),
+    });
+    return {
+        kind: 'recorded',
+        statePath: args.target.statePath,
+        runDir: nextState.runDir,
+        nextState,
+        logger,
+        recoveryTurns: nextState.interactiveBlockedRecovery?.turns.length ?? 0,
+        terminalDirectivePending: false,
+        resumeCommand,
+    };
+}
+export async function recordRecoveryGuidanceForResolvedRun(args) {
+    const state = await loadState(args.target.statePath);
+    const selectedRunId = getSelectedRunId(state, args.target.selectedRunId);
+    const currentStateDecision = decideResumeAction({
+        state,
+        selectedRunId,
+        statePath: args.target.statePath,
+    });
+    const decision = args.decision?.kind === 'needs_message'
+        ? currentStateDecision
+        : args.decision ?? currentStateDecision;
+    if (state.topLevelMode === 'plan') {
+        return recordPlanReviewGuidance({
+            state,
+            target: args.target,
+            message: args.message,
+            decision,
+        });
+    }
+    if (state.topLevelMode !== 'execute') {
+        throw new Error(getUnsupportedModeMessage(state));
+    }
+    if (decision.kind === 'pending_message') {
+        return {
+            kind: 'pending',
+            guidanceKind: 'interactive_blocked_recovery',
+            statePath: args.target.statePath,
+            runDir: state.runDir,
+            message: decision.reason,
+            pendingTurn: getPendingRecoveryTurn(state),
+            recoveryTurns: state.interactiveBlockedRecovery?.turns.length ?? 0,
+            resumeCommand: decision.resumeCommand,
+        };
+    }
+    if (decision.kind !== 'needs_message') {
+        throw new Error(formatGuidanceDecisionRejection(decision));
+    }
+    if (state.phase !== 'interactive_blocked_recovery' || !state.interactiveBlockedRecovery) {
+        throw new Error(describeGuidanceStateProblem(state, args.target));
+    }
+    const resumeCommand = getResumeCommand(state, args.target);
+    assertAgentConfigSupportsResume(state.agentConfig, state, { context: 'record recovery guidance for resume' });
+    const logger = new RunLogger(state.runDir);
+    await logger.event('run.resumed', {
+        statePath: args.target.statePath,
+        phase: state.phase,
+        status: state.status,
+        agentConfig: state.agentConfig,
+    });
+    await logUserGuidanceApplied(logger);
+    try {
+        const nextState = await recordInteractiveBlockedRecoveryGuidance(args.target.statePath, args.message, logger);
+        return {
+            kind: 'recorded',
+            statePath: args.target.statePath,
+            runDir: nextState.runDir,
+            nextState,
+            logger,
+            recoveryTurns: nextState.interactiveBlockedRecovery?.turns.length ?? 0,
+            terminalDirectivePending: nextState.interactiveBlockedRecovery?.pendingDirective?.terminalOnly ?? false,
+            resumeCommand,
+        };
+    }
+    catch (error) {
+        if (error instanceof InteractiveBlockedRecoveryPendingTurnError) {
+            return {
+                kind: 'pending',
+                guidanceKind: 'interactive_blocked_recovery',
+                statePath: args.target.statePath,
+                runDir: state.runDir,
+                message: error.message,
+                pendingTurn: error.pendingTurn,
+                recoveryTurns: state.interactiveBlockedRecovery.turns.length,
+                resumeCommand,
+            };
+        }
+        throw error;
+    }
+}