@navels/neal 0.1.0

package/dist/neal/agents/structured-coder.js

@@ -0,0 +1,82 @@
+import { getAgentTurnRetryLimit, getAgentTurnStartupTimeoutMs, getApiRetryLimit, getInactivityTimeoutMs } from '../config.js';
+import { runWithAgentTurnLiveness } from '../providers/liveness.js';
+import { getCoderAdapter } from '../providers/registry.js';
+import { createProviderTelemetrySink } from '../providers/telemetry.js';
+import { isNealProviderError } from '../providers/types.js';
+export class CoderRoundError extends Error {
+    sessionHandle;
+    providerError;
+    kind;
+    retryable;
+    constructor(providerError) {
+        super(providerError.message);
+        this.name = 'CoderRoundError';
+        this.sessionHandle = providerError.sessionHandle;
+        this.providerError = providerError;
+        this.kind = providerError.kind;
+        this.retryable = providerError.retryable;
+    }
+}
+export function translateCoderProviderError(error) {
+    if (isNealProviderError(error)) {
+        return new CoderRoundError(error);
+    }
+    return error;
+}
+function getCoderRuntimeOptions(cwd) {
+    return {
+        inactivityTimeoutMs: getInactivityTimeoutMs(cwd),
+    };
+}
+function createCoderProviderEventSink(args) {
+    return createProviderTelemetrySink({
+        logger: args.logger,
+        provider: args.coder.provider,
+        role: 'coder',
+        ...(args.label ? { label: args.label } : {}),
+        cwd: args.cwd,
+    });
+}
+export async function runCoderStructuredPrompt(args) {
+    try {
+        const coder = getCoderAdapter(args.coder);
+        return await runWithAgentTurnLiveness({
+            provider: args.coder.provider,
+            role: 'coder',
+            ...(args.telemetryLabel ? { label: args.telemetryLabel } : {}),
+            startupTimeoutMs: Math.min(getAgentTurnStartupTimeoutMs(args.cwd), getInactivityTimeoutMs(args.cwd)),
+            // Resumed sessions never retry in the supervisor; the orchestrator's
+            // fresh-session retry owns recovery so session-handle state stays
+            // consistent.
+            retryLimit: args.resumeHandle ? 0 : getAgentTurnRetryLimit(args.cwd),
+            logger: args.logger,
+            baseSink: createCoderProviderEventSink({
+                coder: args.coder,
+                cwd: args.cwd,
+                label: args.telemetryLabel,
+                logger: args.logger,
+            }),
+            run: (events, attempt) => coder.runStructuredPrompt({
+                cwd: args.cwd,
+                prompt: args.prompt,
+                label: args.label,
+                schema: args.schema,
+                structuredJsonProtocol: args.structuredJsonProtocol,
+                toolPolicy: args.toolPolicy,
+                ...getCoderRuntimeOptions(args.cwd),
+                // Resumed sessions never retry in-round; the orchestrator's
+                // fresh-session retry owns recovery.
+                apiRetryLimit: args.resumeHandle ? 0 : getApiRetryLimit(args.cwd),
+                resumeHandle: args.resumeHandle,
+                // Guarded so an abandoned attempt's late session handle can never
+                // overwrite a newer attempt's handle.
+                onSessionStarted: attempt.guard(args.onSessionStarted),
+                signal: attempt.signal,
+                events,
+            }),
+        });
+    }
+    catch (error) {
+        throw translateCoderProviderError(error);
+    }
+}

package/dist/neal/agents/structured-json.js

@@ -0,0 +1,528 @@
+import { NealProviderError } from '../providers/types.js';
+const SUMMARY_MAX_LENGTH = 800;
+const ORIGINAL_RESPONSE_MAX_LENGTH = 12000;
+const NEAL_JSON_OPENING_FENCE_PATTERN = /^[ \t]*```[ \t]*neal-json[ \t]*$/;
+const CLOSING_FENCE_PATTERN = /^[ \t]*```[ \t]*$/;
+export function buildStructuredJsonPrompt(basePrompt, protocol) {
+    const schemaDescription = typeof protocol.schema === 'string' ? protocol.schema : JSON.stringify(protocol.schema, null, 2);
+    const allowProseBeforeBlock = protocol.allowProseBeforeBlock ?? true;
+    const lines = [
+        basePrompt.trimEnd(),
+        '',
+        'Neal structured control protocol:',
+        `- Protocol: ${protocol.protocol}`,
+        `- Schema label: ${protocol.schemaLabel}`,
+        allowProseBeforeBlock
+            ? '- You may include concise useful prose before the control payload.'
+            : '- Do not include prose outside the control payload.',
+        '- End your response with exactly one final fenced ```neal-json JSON block.',
+        '- No non-whitespace content may appear after the closing fence.',
+        '- The fenced JSON must be a single JSON object that satisfies this schema or schema summary:',
+        fence(schemaDescription, 'json'),
+    ];
+    if (protocol.responseShapeHint?.trim()) {
+        lines.push('', 'Response shape guidance:', protocol.responseShapeHint.trim());
+    }
+    if (protocol.examplePayload !== undefined) {
+        lines.push('', 'Example control payload:', fence(JSON.stringify(protocol.examplePayload, null, 2), 'json'));
+    }
+    return lines.join('\n');
+}
+export function extractStructuredJsonPayload(assistantText) {
+    const blocks = findNealJsonBlocks(assistantText);
+    if (blocks.length > 1) {
+        return {
+            ok: false,
+            errorKind: 'multiple_control_blocks',
+            errorSummary: `Expected exactly one final neal-json control block, but found ${blocks.length}.`,
+            prose: assistantText.trim(),
+            rawJson: null,
+        };
+    }
+    if (blocks.length === 1) {
+        const block = blocks[0];
+        const trailing = assistantText.slice(block.end);
+        const prose = assistantText.slice(0, block.start).trim();
+        if (trailing.trim().length > 0) {
+            return {
+                ok: false,
+                errorKind: 'non_final_control_block',
+                errorSummary: 'The neal-json control block must be the final non-whitespace content.',
+                prose,
+                rawJson: block.rawJson,
+            };
+        }
+        return parseExtractedJson({
+            source: 'neal-json-block',
+            prose,
+            rawJson: block.rawJson,
+            malformedSummaryPrefix: 'The neal-json control block contained malformed JSON',
+        });
+    }
+    const trimmed = assistantText.trim();
+    if (!looksLikeRawJsonObject(trimmed)) {
+        return {
+            ok: false,
+            errorKind: 'missing_control_block',
+            errorSummary: 'Expected a final neal-json control block or a raw whole-response JSON object.',
+            prose: trimmed,
+            rawJson: null,
+        };
+    }
+    // Compatibility tolerance for pre-migration/local mocks that return only a
+    // JSON object. The prompt contract still asks providers for a final
+    // fenced neal-json block, and docs should describe raw JSON as tolerated,
+    // not preferred.
+    return parseExtractedJson({
+        source: 'raw-json',
+        prose: '',
+        rawJson: trimmed,
+        malformedSummaryPrefix: 'The raw JSON response was invalid',
+    });
+}
+export function validateStructuredJsonPayload(assistantText, validator) {
+    const extraction = extractStructuredJsonPayload(assistantText);
+    if (!extraction.ok) {
+        return {
+            ok: false,
+            phase: 'extraction',
+            errorKind: extraction.errorKind,
+            errorSummary: extraction.errorSummary,
+            extraction,
+        };
+    }
+    try {
+        return {
+            ...extraction,
+            structured: validator(extraction.payload),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            phase: 'validation',
+            errorKind: 'schema_invalid',
+            errorSummary: `Extracted JSON failed schema validation: ${summarizeError(error)}`,
+            extraction,
+        };
+    }
+}
+export function buildStructuredJsonRepairPrompt(args) {
+    const issueSummaries = [
+        args.extractionErrorSummary ? `Extraction or parse issue: ${args.extractionErrorSummary}` : null,
+        args.validationErrorSummary ? `Validation issue: ${args.validationErrorSummary}` : null,
+    ].filter((line) => line !== null);
+    const schemaDescription = typeof args.schema === 'string' ? args.schema : JSON.stringify(args.schema, null, 2);
+    const invalidJsonSection = args.invalidJson === undefined || args.invalidJson === null
+        ? 'No JSON payload was extracted.'
+        : fence(args.invalidJson, 'json');
+    return [
+        `You are repairing a Neal structured control payload for schema "${args.schemaLabel}".`,
+        `Repair attempt ${args.attemptNumber} of ${args.attemptLimit}.`,
+        '',
+        'Preserve the original control decision and substantive meaning. Do not inspect the repository, run tools, request more context, or invent new implementation or review work.',
+        'Return only a valid repaired response: either raw whole-response JSON object, or prose followed by exactly one final fenced ```neal-json control block. No content may appear after the closing fence.',
+        '',
+        'The JSON object must satisfy this schema or schema summary:',
+        fence(schemaDescription, 'json'),
+        '',
+        'Repair issue summary:',
+        issueSummaries.length > 0 ? issueSummaries.join('\n') : 'The previous response did not produce a valid structured JSON payload.',
+        '',
+        'Extracted invalid JSON, if any:',
+        invalidJsonSection,
+        '',
+        'Original assistant response:',
+        fence(truncateForPrompt(args.originalAssistantText), 'text'),
+    ].join('\n');
+}
+export async function runStructuredJsonProtocol(args) {
+    const wrappedPrompt = buildStructuredJsonPrompt(args.prompt, args.protocol);
+    const initial = await args.runInitial(wrappedPrompt);
+    const initialSessionHandle = initial.sessionHandle ?? args.initialSessionHandle ?? null;
+    await emitStructuredJsonExtractionStarted({
+        ...args,
+        assistantText: initial.assistantText,
+        sessionHandle: initialSessionHandle,
+        attemptNumber: 0,
+    });
+    const initialValidation = validateStructuredJsonPayload(initial.assistantText, args.protocol.validator);
+    if (initialValidation.ok) {
+        await emitStructuredOutputReceived({
+            ...args,
+            validation: initialValidation,
+            assistantTextLength: initial.assistantText.length,
+            sessionHandle: initialSessionHandle,
+            attemptNumber: 0,
+        });
+        return {
+            sessionHandle: initialSessionHandle,
+            structured: initialValidation.structured,
+        };
+    }
+    await emitStructuredJsonFailure({
+        ...args,
+        failure: initialValidation,
+        assistantTextLength: initial.assistantText.length,
+        sessionHandle: initialSessionHandle,
+        attemptNumber: 0,
+    });
+    let repairResult;
+    try {
+        repairResult = await runStructuredJsonRepairLoop({
+            originalAssistantText: initial.assistantText,
+            initialFailure: initialValidation,
+            schemaLabel: args.protocol.schemaLabel,
+            schema: args.protocol.schema,
+            attemptLimit: args.protocol.repairAttemptLimit,
+            validator: args.protocol.validator,
+            callRepair: async ({ prompt, attemptNumber, attemptLimit }) => {
+                await emitStructuredJsonRepairStarted({
+                    ...args,
+                    assistantTextLength: initial.assistantText.length,
+                    sessionHandle: initialSessionHandle,
+                    attemptNumber,
+                    attemptLimit,
+                });
+                return args.runRepair(prompt, attemptNumber);
+            },
+        });
+    }
+    catch (error) {
+        await emitStructuredJsonRepairFailed({
+            ...args,
+            failure: initialValidation,
+            assistantTextLength: initial.assistantText.length,
+            sessionHandle: initialSessionHandle,
+            attemptNumber: 0,
+            message: 'Structured JSON repair failed before producing a valid Neal payload.',
+            cause: error,
+        });
+        throw error;
+    }
+    for (const attempt of repairResult.attempts) {
+        if (!attempt.result.ok) {
+            await emitStructuredJsonFailure({
+                ...args,
+                failure: attempt.result,
+                assistantTextLength: initial.assistantText.length,
+                sessionHandle: initialSessionHandle ?? attempt.sessionHandle,
+                attemptNumber: attempt.attemptNumber,
+                repairSessionHandle: attempt.sessionHandle,
+            });
+        }
+    }
+    if (repairResult.ok) {
+        const returnedSessionHandle = initialSessionHandle ?? repairResult.sessionHandle;
+        await emitStructuredJsonRepairSucceeded({
+            ...args,
+            validation: repairResult.result,
+            assistantTextLength: initial.assistantText.length,
+            sessionHandle: returnedSessionHandle,
+            attemptNumber: repairResult.attemptNumber,
+            repairSessionHandle: repairResult.sessionHandle,
+        });
+        await emitStructuredOutputReceived({
+            ...args,
+            validation: repairResult.result,
+            assistantTextLength: initial.assistantText.length,
+            sessionHandle: returnedSessionHandle,
+            attemptNumber: repairResult.attemptNumber,
+            repairSessionHandle: repairResult.sessionHandle,
+        });
+        return {
+            sessionHandle: returnedSessionHandle,
+            structured: repairResult.result.structured,
+        };
+    }
+    await emitStructuredJsonRepairFailed({
+        ...args,
+        failure: repairResult.lastFailure,
+        assistantTextLength: initial.assistantText.length,
+        sessionHandle: initialSessionHandle,
+        attemptNumber: repairResult.attempts.at(-1)?.attemptNumber ?? args.protocol.repairAttemptLimit,
+        repairSessionHandle: repairResult.attempts.at(-1)?.sessionHandle ?? null,
+        message: 'Structured JSON repair attempts were exhausted.',
+    });
+    throw buildStructuredJsonProviderError(args, {
+        message: `Neal structured control payload remained invalid after ${args.protocol.repairAttemptLimit} repair attempt(s): ${repairResult.lastFailure.errorSummary}`,
+        kind: 'structured_output_invalid',
+        sessionHandle: initialSessionHandle,
+        cause: repairResult.lastFailure,
+    });
+}
+export async function runStructuredJsonRepairLoop(args) {
+    if (!Number.isSafeInteger(args.attemptLimit) || args.attemptLimit < 1) {
+        throw new Error('Structured JSON repair attemptLimit must be a positive safe integer.');
+    }
+    const attempts = [];
+    let lastFailure = args.initialFailure;
+    for (let attemptNumber = 1; attemptNumber <= args.attemptLimit; attemptNumber += 1) {
+        const prompt = buildStructuredJsonRepairPrompt({
+            originalAssistantText: args.originalAssistantText,
+            invalidJson: getInvalidJson(lastFailure),
+            extractionErrorSummary: lastFailure.phase === 'extraction' ? lastFailure.errorSummary : null,
+            validationErrorSummary: lastFailure.phase === 'validation' ? lastFailure.errorSummary : null,
+            schemaLabel: args.schemaLabel,
+            schema: args.schema,
+            attemptNumber,
+            attemptLimit: args.attemptLimit,
+        });
+        const repairResponse = normalizeRepairCallResult(await args.callRepair({
+            prompt,
+            attemptNumber,
+            attemptLimit: args.attemptLimit,
+        }));
+        const result = validateStructuredJsonPayload(repairResponse.assistantText, args.validator);
+        const attempt = {
+            attemptNumber,
+            sessionHandle: repairResponse.sessionHandle,
+            result,
+        };
+        attempts.push(attempt);
+        if (result.ok) {
+            return {
+                ok: true,
+                attemptNumber,
+                sessionHandle: repairResponse.sessionHandle,
+                result,
+                attempts,
+            };
+        }
+        lastFailure = result;
+    }
+    return {
+        ok: false,
+        attempts,
+        lastFailure,
+    };
+}
+function buildStructuredJsonProviderError(args, errorArgs) {
+    if (args.createProviderError) {
+        return args.createProviderError(errorArgs);
+    }
+    return new NealProviderError({
+        message: errorArgs.message,
+        provider: args.provider,
+        role: args.role,
+        sessionHandle: errorArgs.sessionHandle,
+        kind: errorArgs.kind,
+        retryable: false,
+        cause: errorArgs.cause,
+    });
+}
+async function emitStructuredJsonExtractionStarted(args) {
+    await emitStructuredJsonEvent(args.events, {
+        type: 'tool_progress',
+        provider: args.provider,
+        role: args.role,
+        label: args.label,
+        sessionHandle: args.sessionHandle,
+        toolName: 'structured_json_extraction_started',
+        message: 'Extracting Neal structured control payload.',
+        providerData: buildStructuredJsonProtocolProviderData(args),
+    });
+}
+async function emitStructuredJsonFailure(args) {
+    await emitStructuredJsonEvent(args.events, {
+        type: 'tool_progress',
+        provider: args.provider,
+        role: args.role,
+        label: args.label,
+        sessionHandle: args.sessionHandle,
+        toolName: args.failure.phase === 'validation'
+            ? 'structured_json_validation_failed'
+            : 'structured_json_extraction_failed',
+        message: args.failure.phase === 'validation'
+            ? 'Neal structured control payload failed validation.'
+            : 'Neal structured control payload could not be extracted or parsed.',
+        isError: true,
+        providerData: buildStructuredJsonProtocolProviderData(args),
+    });
+}
+async function emitStructuredJsonRepairStarted(args) {
+    await emitStructuredJsonEvent(args.events, {
+        type: 'tool_progress',
+        provider: args.provider,
+        role: args.role,
+        label: args.label,
+        sessionHandle: args.sessionHandle,
+        toolName: 'structured_json_repair_started',
+        message: `Repairing Neal structured control payload (${args.attemptNumber}/${args.attemptLimit}).`,
+        providerData: {
+            ...buildStructuredJsonProtocolProviderData(args),
+            attemptLimit: args.attemptLimit,
+        },
+    });
+}
+async function emitStructuredJsonRepairSucceeded(args) {
+    await emitStructuredJsonEvent(args.events, {
+        type: 'tool_progress',
+        provider: args.provider,
+        role: args.role,
+        label: args.label,
+        sessionHandle: args.sessionHandle,
+        toolName: 'structured_json_repair_succeeded',
+        message: 'Structured JSON repair produced a valid Neal payload.',
+        providerData: buildStructuredJsonProtocolProviderData(args),
+    });
+}
+async function emitStructuredJsonRepairFailed(args) {
+    await emitStructuredJsonEvent(args.events, {
+        type: 'tool_progress',
+        provider: args.provider,
+        role: args.role,
+        label: args.label,
+        sessionHandle: args.sessionHandle,
+        toolName: 'structured_json_repair_failed',
+        message: args.message,
+        isError: true,
+        providerData: {
+            ...buildStructuredJsonProtocolProviderData(args),
+            ...(args.cause instanceof Error ? { errorMessage: args.cause.message } : {}),
+        },
+    });
+}
+async function emitStructuredOutputReceived(args) {
+    await emitStructuredJsonEvent(args.events, {
+        type: 'structured_output_received',
+        provider: args.provider,
+        role: args.role,
+        label: args.label,
+        sessionHandle: args.sessionHandle,
+        providerData: buildStructuredJsonProtocolProviderData(args),
+    });
+}
+async function emitStructuredJsonEvent(events, event) {
+    await events?.(event);
+}
+function buildStructuredJsonProtocolProviderData(args) {
+    return {
+        protocol: args.protocol.protocol,
+        schemaLabel: args.protocol.schemaLabel,
+        attemptNumber: args.attemptNumber,
+        repairAttemptLimit: args.protocol.repairAttemptLimit,
+        assistantTextLength: args.assistantTextLength ?? args.assistantText?.length ?? 0,
+        extractedJsonLength: args.validation?.rawJson.length ?? args.failure?.extraction.rawJson?.length ?? 0,
+        ...(args.validation ? { source: args.validation.source } : {}),
+        ...(args.failure?.phase === 'extraction' ? { parseErrorSummary: args.failure.errorSummary } : {}),
+        ...(args.failure?.phase === 'validation' ? { validationErrorSummary: args.failure.errorSummary } : {}),
+        ...(args.initialSessionHandle !== undefined ? { originalSessionHandle: args.initialSessionHandle } : {}),
+        ...(args.repairSessionHandle !== undefined ? { repairSessionHandle: args.repairSessionHandle } : {}),
+    };
+}
+function findNealJsonBlocks(assistantText) {
+    const blocks = [];
+    const lines = splitLinesWithOffsets(assistantText);
+    for (let index = 0; index < lines.length; index += 1) {
+        const openingLine = lines[index];
+        if (!NEAL_JSON_OPENING_FENCE_PATTERN.test(openingLine.text)) {
+            continue;
+        }
+        for (let closingIndex = index + 1; closingIndex < lines.length; closingIndex += 1) {
+            const closingLine = lines[closingIndex];
+            if (!CLOSING_FENCE_PATTERN.test(closingLine.text)) {
+                continue;
+            }
+            blocks.push({
+                start: openingLine.start,
+                end: closingLine.end,
+                rawJson: stripSingleTrailingLineBreak(assistantText.slice(openingLine.end, closingLine.start)),
+            });
+            index = closingIndex;
+            break;
+        }
+    }
+    return blocks;
+}
+function splitLinesWithOffsets(text) {
+    const lines = [];
+    let start = 0;
+    while (start < text.length) {
+        const newlineIndex = text.indexOf('\n', start);
+        const end = newlineIndex === -1 ? text.length : newlineIndex + 1;
+        const rawLine = text.slice(start, end);
+        const textWithoutLineBreak = rawLine.replace(/\r?\n$/, '');
+        lines.push({
+            text: textWithoutLineBreak,
+            start,
+            end,
+        });
+        start = end;
+    }
+    return lines;
+}
+function stripSingleTrailingLineBreak(value) {
+    return value.replace(/\r?\n$/, '');
+}
+function parseExtractedJson(args) {
+    try {
+        const payload = JSON.parse(args.rawJson);
+        if (!isJsonObject(payload)) {
+            return {
+                ok: false,
+                errorKind: 'malformed_json',
+                errorSummary: `${args.malformedSummaryPrefix}: expected a single JSON object.`,
+                prose: args.prose,
+                rawJson: args.rawJson,
+            };
+        }
+        return {
+            ok: true,
+            source: args.source,
+            prose: args.prose,
+            rawJson: args.rawJson,
+            payload,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errorKind: 'malformed_json',
+            errorSummary: `${args.malformedSummaryPrefix}: ${summarizeError(error)}`,
+            prose: args.prose,
+            rawJson: args.rawJson,
+        };
+    }
+}
+function looksLikeRawJsonObject(trimmed) {
+    return trimmed.startsWith('{') || trimmed.startsWith('[');
+}
+function isJsonObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeRepairCallResult(result) {
+    if (typeof result === 'string') {
+        return {
+            assistantText: result,
+            sessionHandle: null,
+        };
+    }
+    return {
+        assistantText: result.assistantText,
+        sessionHandle: result.sessionHandle ?? null,
+    };
+}
+function getInvalidJson(failure) {
+    return failure.extraction.rawJson;
+}
+function summarizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return limitOneLine(message, SUMMARY_MAX_LENGTH);
+}
+function limitOneLine(value, maxLength) {
+    const oneLine = value.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= maxLength) {
+        return oneLine;
+    }
+    return `${oneLine.slice(0, maxLength - 1)}…`;
+}
+function truncateForPrompt(value) {
+    if (value.length <= ORIGINAL_RESPONSE_MAX_LENGTH) {
+        return value;
+    }
+    return `${value.slice(0, ORIGINAL_RESPONSE_MAX_LENGTH)}\n[truncated ${value.length - ORIGINAL_RESPONSE_MAX_LENGTH} byte(s)]`;
+}
+function fence(value, language) {
+    return `\`\`\`${language}\n${value}\n\`\`\``;
+}

package/dist/neal/agents.js

@@ -0,0 +1,4 @@
+export * from './agents/prompts.js';
+export * from './agents/schemas.js';
+export * from './agents/rounds.js';
+export * from './agents/structured-coder.js';

package/dist/neal/atomic-write.js

@@ -0,0 +1,18 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+export async function writeJsonAtomic(path, value) {
+    await writeTextAtomic(path, JSON.stringify(value, null, 2) + '\n');
+}
+export async function writeTextAtomic(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    const tempPath = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(tempPath, content, 'utf8');
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}