@navels/neal 0.1.0

package/dist/neal/context/artifacts.js

@@ -0,0 +1,140 @@
+import { open, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+export const DEFAULT_CONTEXT_ARTIFACT_BYTE_LIMIT = 16 * 1024;
+export const DEFAULT_CONTEXT_TOTAL_BYTE_LIMIT = 96 * 1024;
+export async function readBoundedArtifact(request, budget) {
+    if (budget.usedBytes >= budget.totalByteLimit) {
+        return omittedArtifact(request, 'total byte limit reached');
+    }
+    let fileStat;
+    try {
+        fileStat = await stat(request.path);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return omittedArtifact(request, 'missing');
+        }
+        throw error;
+    }
+    if (!fileStat.isFile()) {
+        return omittedArtifact(request, 'not a regular file');
+    }
+    const availableBytes = Math.max(0, budget.totalByteLimit - budget.usedBytes);
+    const byteLimit = Math.min(budget.perArtifactByteLimit, availableBytes);
+    if (byteLimit <= 0) {
+        return omittedArtifact(request, 'total byte limit reached');
+    }
+    const content = await readFileWindow(request.path, fileStat.size, byteLimit, request.readStrategy ?? 'head');
+    budget.usedBytes += content.byteLength;
+    return {
+        label: request.label,
+        kind: request.kind,
+        content: content.text,
+        byteLength: content.byteLength,
+        truncated: fileStat.size > content.bytesRead || content.droppedPartialLine,
+        omitted: false,
+        omissionReason: null,
+    };
+}
+export function makeBoundedInlineArtifact(citation, content, budget) {
+    if (budget.usedBytes >= budget.totalByteLimit) {
+        return omittedArtifact(citation, 'total byte limit reached');
+    }
+    const availableBytes = Math.max(0, budget.totalByteLimit - budget.usedBytes);
+    const byteLimit = Math.min(budget.perArtifactByteLimit, availableBytes);
+    const buffer = Buffer.from(content, 'utf8');
+    const truncated = buffer.byteLength > byteLimit;
+    const boundedBuffer = truncated ? buffer.subarray(0, byteLimit) : buffer;
+    const boundedContent = boundedBuffer.toString('utf8');
+    const byteLength = boundedBuffer.byteLength;
+    budget.usedBytes += byteLength;
+    return {
+        ...citation,
+        content: boundedContent,
+        byteLength,
+        truncated,
+        omitted: false,
+        omissionReason: null,
+    };
+}
+export async function findLatestRetrospectiveArtifact(runDir) {
+    const defaultPath = join(runDir, 'RETROSPECTIVE.md');
+    try {
+        const defaultStat = await stat(defaultPath);
+        if (defaultStat.isFile()) {
+            return {
+                label: 'RETROSPECTIVE.md',
+                kind: 'run_artifact',
+                path: defaultPath,
+            };
+        }
+    }
+    catch (error) {
+        if (!isNotFoundError(error)) {
+            throw error;
+        }
+    }
+    let entries;
+    try {
+        entries = await readdir(runDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+    const names = entries
+        .filter((entry) => entry.isFile() && /^RETROSPECTIVE-.+\.md$/.test(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+    const latestName = names.at(-1);
+    if (!latestName) {
+        return null;
+    }
+    return {
+        label: latestName,
+        kind: 'run_artifact',
+        path: join(runDir, latestName),
+    };
+}
+function omittedArtifact(citation, reason) {
+    return {
+        ...citation,
+        content: '',
+        byteLength: 0,
+        truncated: false,
+        omitted: true,
+        omissionReason: reason,
+    };
+}
+async function readFileWindow(path, fileSize, byteLimit, strategy) {
+    const file = await open(path, 'r');
+    try {
+        const length = Math.min(fileSize, byteLimit);
+        const start = strategy === 'tail' ? Math.max(0, fileSize - length) : 0;
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await file.read(buffer, 0, length, start);
+        let boundedBuffer = buffer.subarray(0, bytesRead);
+        let droppedPartialLine = false;
+        if (strategy === 'tail' && start > 0) {
+            const newlineIndex = boundedBuffer.indexOf('\n');
+            if (newlineIndex >= 0) {
+                boundedBuffer = boundedBuffer.subarray(newlineIndex + 1);
+                droppedPartialLine = true;
+            }
+        }
+        return {
+            text: boundedBuffer.toString('utf8'),
+            byteLength: boundedBuffer.byteLength,
+            bytesRead,
+            droppedPartialLine,
+        };
+    }
+    finally {
+        await file.close();
+    }
+}
+function isNotFoundError(error) {
+    return Boolean(error && typeof error === 'object' && error.code === 'ENOENT');
+}

package/dist/neal/context/context.js

@@ -0,0 +1,324 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { getFinalCompletionReviewArtifactPath } from '../final-completion-review.js';
+import { getCurrentRunPointerPath, resolveRunStatePath } from '../run-registry.js';
+import { getRunDisplayStatus } from '../run-status.js';
+import { getRunStatePath, loadState } from '../state.js';
+import { getNealDir } from '../storage-paths.js';
+import { formatStatusNextActionForState } from '../status.js';
+import { DEFAULT_CONTEXT_ARTIFACT_BYTE_LIMIT, DEFAULT_CONTEXT_TOTAL_BYTE_LIMIT, findLatestRetrospectiveArtifact, makeBoundedInlineArtifact, readBoundedArtifact, } from './artifacts.js';
+const execFileAsync = promisify(execFile);
+const GIT_RECENT_COMMIT_LIMIT = 5;
+export async function buildLocalNealContextPack(args) {
+    const cwd = resolve(args.cwd);
+    const createdAt = (args.now ?? new Date()).toISOString();
+    const perArtifactByteLimit = args.perArtifactByteLimit ?? DEFAULT_CONTEXT_ARTIFACT_BYTE_LIMIT;
+    const totalByteLimit = args.totalByteLimit ?? DEFAULT_CONTEXT_TOTAL_BYTE_LIMIT;
+    const budget = {
+        perArtifactByteLimit,
+        totalByteLimit,
+        usedBytes: 0,
+    };
+    const warnings = [];
+    const artifacts = [];
+    const stateResolution = await loadContextState(cwd, args.statePath ?? null, warnings);
+    if (stateResolution.state) {
+        for (const request of await buildRunArtifactRequests(stateResolution.state)) {
+            artifacts.push(await readBoundedArtifact(request, budget));
+        }
+    }
+    if (args.planPath) {
+        const planPath = resolvePath(cwd, args.planPath);
+        artifacts.push(await readBoundedArtifact({
+            label: args.planPath,
+            kind: 'plan',
+            path: planPath,
+        }, budget));
+    }
+    for (const request of buildGuidanceArtifactRequests(cwd)) {
+        artifacts.push(await readBoundedArtifact(request, budget));
+    }
+    const gitContext = await buildGitContext(cwd, warnings);
+    if (gitContext) {
+        artifacts.push(makeBoundedInlineArtifact({ label: 'git context', kind: 'git' }, gitContext, budget));
+    }
+    const suggestedActions = buildSuggestedActions(stateResolution, artifacts, cwd);
+    const citations = artifacts
+        .filter((artifact) => !artifact.omitted)
+        .map(({ label, kind }) => ({ label, kind }));
+    return {
+        version: 1,
+        createdAt,
+        cwd,
+        state: stateResolution.state ? buildContextState(cwd, stateResolution) : null,
+        artifacts,
+        citations,
+        suggestedActions,
+        limits: {
+            perArtifactByteLimit,
+            totalByteLimit,
+            totalArtifactBytes: budget.usedBytes,
+            truncatedArtifactCount: artifacts.filter((artifact) => artifact.truncated).length,
+            omittedArtifactCount: artifacts.filter((artifact) => artifact.omitted).length,
+        },
+        warnings,
+    };
+}
+function buildContextState(cwd, stateResolution) {
+    const state = stateResolution.state;
+    if (!state) {
+        throw new Error('Cannot build Neal context state without a loaded run state');
+    }
+    const displayStatus = getRunDisplayStatus(state);
+    const runId = basename(state.runDir);
+    const latestInteractiveBlockedRecoveryHistory = state.interactiveBlockedRecoveryHistory.at(-1) ?? null;
+    return {
+        statePath: toDisplayPath(cwd, stateResolution.statePath),
+        statePathSource: stateResolution.source,
+        runDir: toDisplayPath(cwd, state.runDir),
+        runDirName: runId,
+        planDoc: state.planDoc,
+        topLevelMode: state.topLevelMode,
+        executionShape: state.executionShape,
+        phase: state.phase,
+        status: state.status,
+        effectiveStatus: displayStatus.effectiveStatus,
+        waitingForOperatorGuidance: displayStatus.waitingForOperatorGuidance,
+        pendingOperatorGuidance: displayStatus.pendingOperatorGuidance,
+        currentScopeNumber: state.currentScopeNumber,
+        blockedFromPhase: state.blockedFromPhase,
+        lastBlockedReason: getLastBlockedReason(state),
+        interactiveBlockedRecovery: state.interactiveBlockedRecovery
+            ? {
+                sourcePhase: state.interactiveBlockedRecovery.sourcePhase,
+                blockedReason: state.interactiveBlockedRecovery.blockedReason,
+                turns: state.interactiveBlockedRecovery.turns.length,
+                lastHandledTurn: state.interactiveBlockedRecovery.lastHandledTurn,
+                pendingDirective: state.interactiveBlockedRecovery.pendingDirective?.operatorGuidance ?? null,
+                acceptsFreeFormResumeMessage: displayStatus.waitingForOperatorGuidance,
+            }
+            : null,
+        acceptedResumeMessageShapes: getAcceptedResumeMessageShapes(state, runId, displayStatus.waitingForOperatorGuidance),
+        latestInteractiveBlockedRecoveryHistory: latestInteractiveBlockedRecoveryHistory
+            ? {
+                resolvedByAction: latestInteractiveBlockedRecoveryHistory.resolvedByAction,
+                resultPhase: latestInteractiveBlockedRecoveryHistory.resultPhase,
+                blockedReason: latestInteractiveBlockedRecoveryHistory.blockedReason,
+                turns: latestInteractiveBlockedRecoveryHistory.turns.length,
+            }
+            : null,
+        nextAction: formatStatusNextActionForState(state),
+        updatedAt: state.updatedAt,
+    };
+}
+function getAcceptedResumeMessageShapes(state, runId, waitingForOperatorGuidance) {
+    if (waitingForOperatorGuidance) {
+        return [`neal resume --run ${runId} --message "<free-form recovery guidance>"`];
+    }
+    return [];
+}
+function getLastBlockedReason(state) {
+    if (state.interactiveBlockedRecovery?.blockedReason) {
+        return state.interactiveBlockedRecovery.blockedReason;
+    }
+    const blockedScope = [...state.completedScopes].reverse().find((scope) => scope.result === 'blocked' && scope.blocker);
+    return blockedScope?.blocker ?? null;
+}
+async function loadContextState(cwd, inputStatePath, warnings) {
+    const source = inputStatePath ? 'explicit' : 'current_pointer';
+    let statePath;
+    try {
+        statePath = inputStatePath
+            ? resolvePath(cwd, inputStatePath)
+            : (await resolveRunStatePath({ cwd, runId: 'latest' })).statePath;
+    }
+    catch (error) {
+        statePath = inputStatePath ? resolvePath(cwd, inputStatePath) : getCurrentRunPointerPath(cwd);
+        warnings.push(inputStatePath
+            ? `State file could not be resolved: ${error instanceof Error ? error.message : String(error)}`
+            : `Current Neal run pointer could not be resolved: ${error instanceof Error ? error.message : String(error)}`);
+        return {
+            state: null,
+            statePath,
+            source,
+        };
+    }
+    try {
+        const state = await loadState(statePath);
+        return {
+            state,
+            statePath,
+            source,
+        };
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            warnings.push(inputStatePath ? `State file not found: ${inputStatePath}` : 'No .neal/current.json run pointer state file found.');
+            return {
+                state: null,
+                statePath,
+                source,
+            };
+        }
+        warnings.push(`State file could not be read: ${error instanceof Error ? error.message : String(error)}`);
+        return {
+            state: null,
+            statePath,
+            source,
+        };
+    }
+}
+async function buildRunArtifactRequests(state) {
+    const requests = [
+        {
+            label: 'RUN_STATE.json',
+            kind: 'state',
+            path: getRunStatePath(state.runDir),
+        },
+    ];
+    requests.push({
+        label: 'events.ndjson',
+        kind: 'run_artifact',
+        path: join(state.runDir, 'events.ndjson'),
+        readStrategy: 'tail',
+    }, {
+        label: 'plan-progress.json',
+        kind: 'run_artifact',
+        path: state.progressJsonPath,
+    }, {
+        label: 'PLAN_PROGRESS.md',
+        kind: 'run_artifact',
+        path: state.progressMarkdownPath,
+    }, {
+        label: 'REVIEW.md',
+        kind: 'run_artifact',
+        path: state.reviewMarkdownPath,
+    }, {
+        label: 'RECOVERY.md',
+        kind: 'run_artifact',
+        path: state.recoveryMarkdownPath,
+    });
+    const retrospective = await findLatestRetrospectiveArtifact(state.runDir);
+    if (retrospective) {
+        requests.push(retrospective);
+    }
+    requests.push({
+        label: 'FINAL_COMPLETION_REVIEW.md',
+        kind: 'run_artifact',
+        path: getFinalCompletionReviewArtifactPath(state.runDir),
+    });
+    return requests;
+}
+function buildGuidanceArtifactRequests(cwd) {
+    return [
+        {
+            label: 'AGENTS.md',
+            kind: 'guidance',
+            path: join(cwd, 'AGENTS.md'),
+        },
+        {
+            label: '.neal/NOTES.md',
+            kind: 'guidance',
+            path: join(getNealDir(cwd), 'NOTES.md'),
+        },
+    ];
+}
+async function buildGitContext(cwd, warnings) {
+    try {
+        await access(join(cwd, '.git'));
+    }
+    catch {
+        return null;
+    }
+    try {
+        const [statusResult, logResult] = await Promise.all([
+            execFileAsync('git', ['status', '--short'], { cwd }),
+            execFileAsync('git', ['log', `-${GIT_RECENT_COMMIT_LIMIT}`, '--pretty=format:%h %s'], { cwd }),
+        ]);
+        const status = statusResult.stdout.trim();
+        const log = logResult.stdout.trim();
+        return [
+            'git status --short',
+            status || '(clean)',
+            '',
+            `git log -${GIT_RECENT_COMMIT_LIMIT} --pretty=format:%h %s`,
+            log || '(no commits)',
+        ].join('\n');
+    }
+    catch {
+        warnings.push('Git context unavailable.');
+        return null;
+    }
+}
+function buildSuggestedActions(stateResolution, artifacts, cwd) {
+    const state = stateResolution.state;
+    if (!state) {
+        return [];
+    }
+    const target = {
+        runDirName: basename(state.runDir),
+        statePath: toDisplayPath(cwd, getRunStatePath(state.runDir)),
+    };
+    const suggestions = [];
+    const firstInspectableArtifact = artifacts.find((artifact) => !artifact.omitted && artifact.kind !== 'git');
+    if (firstInspectableArtifact) {
+        suggestions.push({
+            type: 'inspect_artifact',
+            label: `Inspect ${firstInspectableArtifact.label}`,
+            target: {
+                ...target,
+                artifactLabel: firstInspectableArtifact.label,
+            },
+            rationale: 'Read a bounded Neal artifact excerpt before taking action.',
+        });
+    }
+    if (state.status === 'blocked') {
+        suggestions.push({
+            type: 'recover',
+            label: 'Recover selected run',
+            target,
+            rationale: 'The selected Neal run is blocked and can accept operator recovery guidance.',
+        });
+    }
+    else if (state.status === 'paused') {
+        suggestions.push({
+            type: 'resume',
+            label: 'Resume selected run',
+            target,
+            rationale: 'The selected Neal run is paused at a scope boundary.',
+        });
+    }
+    else if (state.status === 'running') {
+        suggestions.push({
+            type: 'pause_after_scope',
+            label: 'Pause after current scope',
+            target,
+            rationale: 'The selected Neal run is still running.',
+        });
+    }
+    else if (state.status === 'done' && state.finalCommit) {
+        suggestions.push({
+            type: 'squash',
+            label: 'Review squash opportunity',
+            target,
+            rationale: 'The selected Neal run has a final commit recorded.',
+        });
+    }
+    return suggestions;
+}
+function resolvePath(cwd, path) {
+    return isAbsolute(path) ? path : resolve(cwd, path);
+}
+function toDisplayPath(cwd, path) {
+    const absolutePath = resolvePath(cwd, path);
+    const relativePath = relative(cwd, absolutePath);
+    if (!relativePath.startsWith('..') && !isAbsolute(relativePath)) {
+        return relativePath || '.';
+    }
+    return absolutePath;
+}
+function isNotFoundError(error) {
+    return Boolean(error && typeof error === 'object' && error.code === 'ENOENT');
+}

package/dist/neal/context/inline-review-context.js

@@ -0,0 +1,131 @@
+import { readFile } from 'node:fs/promises';
+import { getProviderDefinition, isRegisteredProviderId } from '../providers/registry.js';
+// Per-section character cap for inlined reviewer context. Mirrors the
+// truncation posture of truncateForPrompt in src/neal/agents/structured-json.ts:
+// truncate with an explicit marker instead of silently dropping content.
+export const INLINE_SECTION_MAX_CHARS = 200_000;
+// Canonical forbidden-phrase list for no-read reviewer prompts. A no-read
+// reviewer prompt must contain no instruction that requires repository, file,
+// tool, or shell access of any kind. Both the prompt-builder implementations
+// and the runtime capture tests assert against this shared list, so a newly
+// added repo-access phrase fails the shared assertion rather than silently
+// passing.
+export const NO_READ_PROMPT_FORBIDDEN_MARKERS = [
+    'repository tools',
+    'repository inspection',
+    'git diff',
+    'git log',
+    'git show',
+    'scratch directory',
+    // "Read <path>"-style pointer phrasings ("Prior review history is available
+    // at <path>", "REVIEW.md is available at <path>", ...).
+    'is available at',
+    'Inspect cited artifacts',
+];
+// True when the configured reviewer provider's structured-advisor role has no
+// repository read access, so Neal must inline the review context (diff, plan,
+// artifacts) into reviewer prompts.
+export function reviewerNeedsInlineContext(reviewer) {
+    if (!isRegisteredProviderId(reviewer.provider)) {
+        return false;
+    }
+    return getProviderDefinition(reviewer.provider).capabilities['structured-advisor'].toolAccess.read === false;
+}
+// Three-way review-doctrine access mode for the configured reviewer provider's
+// structured-advisor role. Unregistered provider ids default to 'tool-access',
+// mirroring reviewerNeedsInlineContext's false. No repository read access
+// selects 'no-read' (Neal inlines the review context); read access without
+// shell access selects 'read-only' (the reviewer inspects the repository with
+// read tools but must not be instructed to run commands); read plus shell
+// access selects 'tool-access'. Write access does not affect review doctrine:
+// reviews never instruct repository mutation.
+export function getReviewerDoctrineAccessMode(reviewer) {
+    if (!isRegisteredProviderId(reviewer.provider)) {
+        return 'tool-access';
+    }
+    const toolAccess = getProviderDefinition(reviewer.provider).capabilities['structured-advisor'].toolAccess;
+    if (toolAccess.read === false) {
+        return 'no-read';
+    }
+    if (toolAccess.shell === false) {
+        return 'read-only';
+    }
+    return 'tool-access';
+}
+// True when the configured reviewer is a read-only reviewer (read tools, no
+// shell) that has no commit-range diff tool of its own, so Neal must inline the
+// commit-range diff into its reviewer prompt. Read-only reviewers that expose a
+// commit-range diff tool (providesRangeDiffTool === true, e.g. generic-agentic)
+// inspect the range with that tool and do not receive an inlined diff; no-read
+// reviewers get the full inlineContext instead, and tool-access reviewers run
+// shell git themselves. The inlined commit-range diff rides a dedicated prompt
+// channel separate from the no-read inlineContext channel, so it never trips
+// resolveReviewerPromptAccessMode's no-read-only inlineContext guard.
+export function readOnlyReviewerNeedsInlinedDiff(reviewer) {
+    if (!isRegisteredProviderId(reviewer.provider)) {
+        return false;
+    }
+    if (getReviewerDoctrineAccessMode(reviewer) !== 'read-only') {
+        return false;
+    }
+    return getProviderDefinition(reviewer.provider).capabilities['structured-advisor'].providesRangeDiffTool !== true;
+}
+// Renders the Neal-inlined commit-range diff section for a read-only reviewer
+// that lacks a commit-range diff tool. Unlike renderInlineReviewerContext (the
+// no-read framing that denies all repository access), this framing affirms the
+// reviewer's read tools and presents the inlined diff only as the source of
+// truth for what the range changed.
+export function renderInlinedRangeDiffSection(args) {
+    return [
+        `## Inlined commit-range diff from Neal (${args.rangeLabel})`,
+        '',
+        'You have read-only repository tools (read and search, no shell) but no commit-range diff tool, so Neal has inlined the commit-range diff below.',
+        'This inlined diff is the source of truth for exactly what this range changed, including deletions and renames that head-state file reads cannot reveal. Use your read tools to verify the surrounding code.',
+        '',
+        args.diff.trim() === '' ? '(empty diff)' : truncateInlineSectionBody(args.diff),
+    ].join('\n');
+}
+// Best-effort artifact read for inline reviewer sections. Missing or
+// unreadable artifacts inline as empty content (callers substitute an explicit
+// "(unavailable)" placeholder) instead of failing the reviewer round.
+export async function readTextForInlineSection(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export function truncateInlineSectionBody(body, maxChars = INLINE_SECTION_MAX_CHARS) {
+    if (body.length <= maxChars) {
+        return body;
+    }
+    return `${body.slice(0, maxChars)}\n[truncated ${body.length - maxChars} character(s)]`;
+}
+export function createInlineSection(title, body) {
+    return {
+        title,
+        body: truncateInlineSectionBody(body),
+    };
+}
+export function renderInlineReviewerContext(context) {
+    return [
+        '## Inlined review context from Neal',
+        '',
+        'You do not have repository, file, shell, or tool access of any kind for this review.',
+        'Neal has inlined every artifact you need below. The inlined sections are the source of truth for this review; judge entirely from this prompt.',
+        'Do not report the lack of repository access as a finding; it is expected for this reviewer configuration.',
+        ...context.sections.flatMap((section) => ['', `### ${section.title}`, '', section.body]),
+    ].join('\n');
+}
+// Implementation-side guard for builder-owned static instruction text in
+// no-read prompt variants. Call it only on Neal-authored instruction lines
+// (never on dynamic content such as diffs, coder-authored justifications, or
+// operator guidance, which may legitimately mention these phrases).
+export function assertNoReadPromptInstructionText(text, label) {
+    const lowered = text.toLowerCase();
+    const violations = NO_READ_PROMPT_FORBIDDEN_MARKERS.filter((marker) => lowered.includes(marker.toLowerCase()));
+    if (violations.length > 0) {
+        throw new Error(`${label} produced no-read reviewer instructions containing forbidden repository-access phrasing: ${violations.join(', ')}`);
+    }
+}