@navels/neal 0.1.0

package/dist/neal/providers/registry.js

@@ -0,0 +1,389 @@
+import { anthropicClaudeProviderDefinition } from './anthropic-claude.js';
+import { genericAgenticProviderDefinition } from './generic-agentic.js';
+import { openAICodexProviderDefinition } from './openai-codex.js';
+import { openAICompatibleProviderDefinition } from './openai-compatible.js';
+// Computed lazily instead of as a top-level constant: openai-compatible.ts
+// imports config.ts, which imports this module, so the definition bindings may
+// still be in their temporal dead zone while this module body evaluates.
+// Every consumer calls listRegisteredProviderDefinitions() at runtime, after
+// the module graph has fully loaded.
+function getBuiltInProviderDefinitions() {
+    return [
+        openAICodexProviderDefinition,
+        anthropicClaudeProviderDefinition,
+        openAICompatibleProviderDefinition,
+        genericAgenticProviderDefinition,
+    ];
+}
+const providerCapabilityOverrides = new Map();
+const providerDefinitionRegistrationsForTesting = new Map();
+function formatProviderValue(value) {
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+function getProviderDefinitionMap() {
+    return new Map(listRegisteredProviderDefinitions().map((definition) => [definition.id, definition]));
+}
+function getProviderAdapterFactories(provider) {
+    const definition = getProviderDefinition(provider);
+    const createCoderAdapter = definition.createCoderAdapter;
+    const createStructuredAdvisorAdapter = definition.createStructuredAdvisorAdapter;
+    const base = {
+        createCoderAdapter: createCoderAdapter
+            ? (config) => createCoderAdapter({ model: config.model, effort: config.effort ?? null })
+            : undefined,
+        createStructuredAdvisorAdapter: createStructuredAdvisorAdapter
+            ? (config) => createStructuredAdvisorAdapter({ model: config.model, effort: config.effort ?? null })
+            : undefined,
+    };
+    const override = providerCapabilityOverrides.get(provider);
+    return override ? { ...base, ...override } : base;
+}
+function listSupportedProvidersForRole(role) {
+    const providers = listRegisteredProviderDefinitions()
+        .filter((definition) => {
+        const adapters = getProviderAdapterFactories(definition.id);
+        return role === 'coder' || role === 'planner'
+            ? adapters.createCoderAdapter
+            : adapters.createStructuredAdvisorAdapter;
+    })
+        .map((definition) => definition.id);
+    return providers.length > 0 ? providers.join(', ') : 'none';
+}
+function getCapabilityReason(requirementContext, capability) {
+    return requirementContext.reasons?.[capability] ?? requirementContext.reason;
+}
+function formatCapabilityName(capability) {
+    return capability.replaceAll('_', ' ');
+}
+function formatRoleConfigKey(role, key) {
+    return `agent.${role}.${key}`;
+}
+function formatConfiguredModel(config) {
+    return config.model === null ? 'null (provider default)' : JSON.stringify(config.model);
+}
+function throwProviderCapabilityError(args) {
+    const context = args.requirementContext.context ? ` Context: ${args.requirementContext.context}.` : '';
+    throw new Error([
+        `Provider capability error for ${args.requirementContext.role} role: configured provider ${JSON.stringify(args.config.provider)} is missing ${formatCapabilityName(args.missingCapability)}.`,
+        `Config keys: ${formatRoleConfigKey(args.requirementContext.role, 'provider')}=${JSON.stringify(args.config.provider)}, ${formatRoleConfigKey(args.requirementContext.role, 'model')}=${formatConfiguredModel(args.config)}.`,
+        `Neal needs this because ${getCapabilityReason(args.requirementContext, args.missingCapability)}.`,
+        `Registered providers: ${formatRegisteredProviderIds()}.`,
+        context.trim(),
+    ].filter(Boolean).join(' '));
+}
+function throwProviderEffortError(args) {
+    const role = args.requirementContext.role;
+    const provider = args.config.provider;
+    const hasSupported = Boolean(args.supportedEfforts && args.supportedEfforts.length > 0);
+    const supportedClause = hasSupported
+        ? `Supported effort values for ${provider}: ${args.supportedEfforts.join(', ')}.`
+        : `Supported effort values for ${provider}: (none).`;
+    const headline = hasSupported
+        ? `Provider config error for ${role} role: provider ${JSON.stringify(provider)} does not support effort ${JSON.stringify(args.effort)}.`
+        : `Provider config error for ${role} role: provider ${JSON.stringify(provider)} does not support configuring effort.`;
+    throw new Error([headline, supportedClause].join(' '));
+}
+function getDefinitionForCapabilityCheck(config, requirementContext) {
+    if (!isRegisteredProviderId(config.provider)) {
+        throwProviderCapabilityError({
+            requirementContext,
+            config,
+            missingCapability: 'registered_provider',
+        });
+    }
+    return getProviderDefinition(config.provider);
+}
+function assertRoleCapabilities(args) {
+    if (!args.capabilities.supported) {
+        throwProviderCapabilityError({
+            requirementContext: args.requirementContext,
+            config: args.config,
+            missingCapability: 'role_support',
+        });
+    }
+    if (args.requirementContext.requireReadToolAccess && !args.capabilities.toolAccess.read) {
+        throwProviderCapabilityError({
+            requirementContext: args.requirementContext,
+            config: args.config,
+            missingCapability: 'read_tool_access',
+        });
+    }
+    if (args.requirementContext.requireReadToolAccessOrInlineReviewerContext &&
+        !args.capabilities.toolAccess.read &&
+        !(args.capabilities.supported && args.capabilities.supportsStructuredOutput)) {
+        throwProviderCapabilityError({
+            requirementContext: args.requirementContext,
+            config: args.config,
+            missingCapability: 'read_tool_access_or_inline_reviewer_context',
+        });
+    }
+    if (args.requirementContext.requireWriteToolAccess && !args.capabilities.toolAccess.write) {
+        throwProviderCapabilityError({
+            requirementContext: args.requirementContext,
+            config: args.config,
+            missingCapability: 'write_tool_access',
+        });
+    }
+    if (args.requirementContext.requireStructuredOutput && !args.capabilities.supportsStructuredOutput) {
+        throwProviderCapabilityError({
+            requirementContext: args.requirementContext,
+            config: args.config,
+            missingCapability: 'structured_output',
+        });
+    }
+    if (args.config.model !== null && !args.capabilities.supportsModelOverride) {
+        throwProviderCapabilityError({
+            requirementContext: args.requirementContext,
+            config: args.config,
+            missingCapability: 'model_override',
+        });
+    }
+    const effort = args.config.effort ?? null;
+    if (effort !== null) {
+        const supportedEfforts = args.capabilities.supportedEfforts;
+        if (!supportedEfforts || supportedEfforts.length === 0 || !supportedEfforts.includes(effort)) {
+            throwProviderEffortError({
+                requirementContext: args.requirementContext,
+                config: args.config,
+                effort,
+                supportedEfforts,
+            });
+        }
+    }
+    if (args.requirementContext.requireSessionResume && !args.capabilities.supportsSessionResume) {
+        throwProviderCapabilityError({
+            requirementContext: args.requirementContext,
+            config: args.config,
+            missingCapability: 'session_resume',
+        });
+    }
+}
+// Registry invariant: every *supported* structured-advisor (reviewer)
+// capability must be read-only. Reviewers inspect work and return verdicts;
+// they never mutate the checkout or run shell commands. Only `write`/`shell`
+// are constrained here — `read` is unconstrained (a reviewer may read the
+// checkout directly, or be a no-read inline-context reviewer). The `coder`
+// capability is intentionally not checked: coders keep write/shell.
+export function assertStructuredAdvisorReadOnly(definition) {
+    const capability = definition.capabilities['structured-advisor'];
+    if (!capability.supported) {
+        return;
+    }
+    const { write, shell } = capability.toolAccess;
+    if (write || shell) {
+        throw new Error([
+            `Provider ${JSON.stringify(definition.id)} declares a structured-advisor capability that is not read-only:`,
+            `reviewers must have write:false and shell:false (read is unconstrained), but got write:${write}, shell:${shell}.`,
+            'Reviewer rounds inspect work and return verdicts; only the coder capability may write or run shell.',
+        ].join(' '));
+    }
+}
+export function listRegisteredProviderDefinitions() {
+    const definitions = [
+        ...getBuiltInProviderDefinitions(),
+        ...providerDefinitionRegistrationsForTesting.values(),
+    ];
+    for (const definition of definitions) {
+        assertStructuredAdvisorReadOnly(definition);
+    }
+    return definitions;
+}
+export function listRegisteredProviderIds() {
+    return listRegisteredProviderDefinitions().map((definition) => definition.id);
+}
+export function formatRegisteredProviderIds() {
+    return listRegisteredProviderIds().join(', ');
+}
+export function isRegisteredProviderId(value) {
+    return typeof value === 'string' && getProviderDefinitionMap().has(value);
+}
+export function parseProviderId(value, context = 'provider') {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`Invalid provider for ${context}: ${formatProviderValue(value)}. Registered providers: ${formatRegisteredProviderIds()}`);
+    }
+    const provider = value.trim();
+    if (!isRegisteredProviderId(provider)) {
+        throw new Error(`Invalid provider for ${context}: ${JSON.stringify(provider)}. Registered providers: ${formatRegisteredProviderIds()}`);
+    }
+    return provider;
+}
+export function getProviderDefinition(id) {
+    const definition = getProviderDefinitionMap().get(id);
+    if (!definition) {
+        throw new Error(`Unsupported provider ${formatProviderValue(id)}. Registered providers: ${formatRegisteredProviderIds()}`);
+    }
+    return definition;
+}
+export function assertProviderSupportsCoder(config, requirementContext) {
+    const definition = getDefinitionForCapabilityCheck(config, requirementContext);
+    const adapters = getProviderAdapterFactories(config.provider);
+    const capabilities = definition.capabilities.coder;
+    assertRoleCapabilities({
+        config,
+        capabilities,
+        requirementContext,
+    });
+    if (!adapters.createCoderAdapter) {
+        throwProviderCapabilityError({
+            requirementContext,
+            config,
+            missingCapability: 'coder_adapter',
+        });
+    }
+}
+export function assertProviderSupportsStructuredAdvisor(config, requirementContext) {
+    const definition = getDefinitionForCapabilityCheck(config, requirementContext);
+    const adapters = getProviderAdapterFactories(config.provider);
+    const capabilities = definition.capabilities['structured-advisor'];
+    assertRoleCapabilities({
+        config,
+        capabilities,
+        requirementContext,
+    });
+    if (!adapters.createStructuredAdvisorAdapter) {
+        throwProviderCapabilityError({
+            requirementContext,
+            config,
+            missingCapability: 'structured_advisor_adapter',
+        });
+    }
+}
+export function assertAgentConfigSupportsWriterRun(agentConfig, options = {}) {
+    const context = options.context ?? 'writer run';
+    assertProviderSupportsCoder(agentConfig.coder, {
+        role: 'coder',
+        context,
+        reason: 'Neal writer runs need a coder provider that can modify the target checkout and return structured continuation payloads',
+        requireWriteToolAccess: true,
+        requireStructuredOutput: true,
+        reasons: {
+            coder_adapter: 'Neal starts coder turns through the configured coder adapter before any scope work can run',
+            write_tool_access: 'plan and execute work may edit plan files, source files, and verification artifacts',
+            structured_output: 'coder response, support response, blocked recovery, and final-completion paths use schema-validated structured coder payloads',
+            model_override: 'a non-null coder model override is configured for this writer run',
+        },
+    });
+    assertProviderSupportsCoder(agentConfig.planner, {
+        role: 'planner',
+        context,
+        reason: 'Neal planning runs need a planner provider backed by the coder adapter so plan authoring can edit plan artifacts and return structured continuation payloads',
+        requireWriteToolAccess: true,
+        requireStructuredOutput: true,
+        reasons: {
+            coder_adapter: 'Neal starts planner turns through the coder adapter before plan authoring can run',
+            write_tool_access: 'planning work may create, refine, and recover plan files',
+            structured_output: 'plan authoring and plan-response paths use schema-validated structured coder payloads',
+            model_override: 'a non-null planner model override is configured for this writer run',
+        },
+    });
+    assertProviderSupportsStructuredAdvisor(agentConfig.reviewer, {
+        role: 'reviewer',
+        context,
+        reason: 'Neal writer runs need a reviewer provider that can inspect work and return structured verdicts',
+        requireReadToolAccessOrInlineReviewerContext: true,
+        requireStructuredOutput: true,
+        reasons: {
+            structured_advisor_adapter: 'reviewer, plan-review, support, and final-completion verdicts run through the structured-advisor adapter',
+            read_tool_access_or_inline_reviewer_context: 'reviewer rounds must either inspect repository state, diffs, and run artifacts directly with read tools, or support structured output so Neal can supply inline reviewer context (full diff, plan document, run artifacts) in the prompt',
+            structured_output: 'reviewer rounds return schema-validated structured verdicts',
+            model_override: 'a non-null reviewer model override is configured for this writer run',
+        },
+    });
+    assertProviderSupportsStructuredAdvisor(agentConfig.coder, {
+        role: 'coder',
+        context,
+        reason: 'the final-completion summary currently uses the configured coder provider through the structured-advisor path',
+        requireStructuredOutput: true,
+        reasons: {
+            structured_advisor_adapter: 'runCoderFinalCompletionSummaryRound obtains a structured-advisor adapter from the coder provider',
+            structured_output: 'the final-completion summary must return a schema-validated structured payload',
+            model_override: 'a non-null coder model override is configured for the final-completion structured-advisor call',
+        },
+    });
+}
+export function assertAgentConfigSupportsResume(agentConfig, state, options = {}) {
+    const context = options.context ?? 'writer run resume';
+    assertAgentConfigSupportsWriterRun(agentConfig, { context });
+    if (state.plannerSessionHandle) {
+        assertProviderSupportsCoder(agentConfig.planner, {
+            role: 'planner',
+            context,
+            reason: 'the selected run has a persisted planner session handle that Neal must resume before continuing plan-authoring work',
+            requireSessionResume: true,
+            reasons: {
+                session_resume: `persisted planner session ${JSON.stringify(state.plannerSessionHandle)} is present`,
+            },
+        });
+    }
+    if (state.coderSessionHandle) {
+        assertProviderSupportsCoder(agentConfig.coder, {
+            role: 'coder',
+            context,
+            reason: 'the selected run has a persisted coder session handle that Neal must resume before continuing writer work',
+            requireSessionResume: true,
+            reasons: {
+                session_resume: `persisted coder session ${JSON.stringify(state.coderSessionHandle)} is present`,
+            },
+        });
+    }
+    if (state.reviewerSessionHandle) {
+        assertProviderSupportsStructuredAdvisor(agentConfig.reviewer, {
+            role: 'reviewer',
+            context,
+            reason: 'the selected run has a persisted reviewer session handle that Neal must resume before continuing reviewer work',
+            requireSessionResume: true,
+            reasons: {
+                session_resume: `persisted reviewer session ${JSON.stringify(state.reviewerSessionHandle)} is present`,
+            },
+        });
+    }
+}
+export function assertSupportedAgentConfig(agentConfig) {
+    assertAgentConfigSupportsWriterRun(agentConfig);
+}
+export function getCoderAdapter(config) {
+    const createCoderAdapter = getProviderAdapterFactories(config.provider).createCoderAdapter;
+    if (createCoderAdapter) {
+        return createCoderAdapter(config);
+    }
+    throw new Error(`Unsupported coder provider: ${config.provider}. Supported today: ${listSupportedProvidersForRole('coder')}`);
+}
+export function getStructuredAdvisorAdapter(config) {
+    const createStructuredAdvisorAdapter = getProviderAdapterFactories(config.provider).createStructuredAdvisorAdapter;
+    if (createStructuredAdvisorAdapter) {
+        return createStructuredAdvisorAdapter(config);
+    }
+    throw new Error(`Unsupported reviewer provider: ${config.provider}. Supported today: ${listSupportedProvidersForRole('reviewer')}`);
+}
+// The two mutators below can substitute adapter factories/definitions after the
+// registry's read-only assertion has run, so they must be structurally
+// unreachable outside the test runner: node:test sets NODE_TEST_CONTEXT in
+// every test process, and no production code path sets it. The clear* helpers
+// stay unguarded — they can only restore production state.
+function assertTestRunnerContext(hook) {
+    if (process.env.NODE_TEST_CONTEXT === undefined) {
+        throw new Error(`${hook} is a test-only registry mutation hook and can only run under the node:test runner ` +
+            '(NODE_TEST_CONTEXT is not set). Production code must never override provider capabilities.');
+    }
+}
+export function setProviderCapabilitiesOverrideForTesting(provider, override) {
+    assertTestRunnerContext('setProviderCapabilitiesOverrideForTesting');
+    providerCapabilityOverrides.set(provider, override);
+}
+export function clearProviderCapabilitiesOverridesForTesting() {
+    providerCapabilityOverrides.clear();
+}
+export function registerProviderDefinitionForTesting(definition) {
+    assertTestRunnerContext('registerProviderDefinitionForTesting');
+    if (isRegisteredProviderId(definition.id)) {
+        throw new Error(`Provider ${JSON.stringify(definition.id)} is already registered`);
+    }
+    assertStructuredAdvisorReadOnly(definition);
+    providerDefinitionRegistrationsForTesting.set(definition.id, definition);
+    return () => {
+        providerDefinitionRegistrationsForTesting.delete(definition.id);
+    };
+}
+export function clearProviderDefinitionRegistrationsForTesting() {
+    providerDefinitionRegistrationsForTesting.clear();
+}

package/dist/neal/providers/telemetry.js

@@ -0,0 +1,208 @@
+import { writeDetail, writeErrorDetail } from '../diagnostic.js';
+import { getHeadCommit } from '../git.js';
+export function providerShortName(provider) {
+    switch (provider) {
+        case 'openai-codex':
+            return 'codex';
+        case 'anthropic-claude':
+            return 'claude';
+        default:
+            return provider;
+    }
+}
+function detailRole(event) {
+    return event.label ?? event.role;
+}
+function detailPrefix(event) {
+    const provider = providerShortName(event.provider);
+    if (event.provider === 'openai-codex' && event.role === 'coder' && !event.label) {
+        return `[${provider}]`;
+    }
+    return `[${provider}:${detailRole(event)}]`;
+}
+function errorDetailPrefix(event) {
+    const prefix = detailPrefix(event);
+    return `${prefix.slice(0, -1)}:error]`;
+}
+function formatExitCode(exitCode) {
+    return typeof exitCode === 'number' ? `exit ${exitCode}` : 'exit unknown';
+}
+async function getGitHeadOrNull(cwd) {
+    try {
+        return await getHeadCommit(cwd);
+    }
+    catch {
+        return null;
+    }
+}
+function commonEventData(event) {
+    return {
+        provider: event.provider,
+        role: event.role,
+        ...(event.label ? { label: event.label } : {}),
+        ...(event.sessionHandle !== undefined ? { sessionHandle: event.sessionHandle } : {}),
+        ...(event.providerData ? { providerData: event.providerData } : {}),
+    };
+}
+async function writeRunEvent(event, options) {
+    const logger = options.logger;
+    if (!logger) {
+        return;
+    }
+    switch (event.type) {
+        case 'session_started':
+            await logger.event('provider.session_started', {
+                ...commonEventData(event),
+                sessionHandle: event.sessionHandle,
+            });
+            break;
+        case 'turn_started':
+            await logger.event('provider.turn_started', commonEventData(event));
+            break;
+        case 'turn_completed':
+            await logger.event('provider.turn_completed', {
+                ...commonEventData(event),
+                ...(event.usage !== undefined ? { usage: event.usage } : {}),
+            });
+            break;
+        case 'tool_started':
+            await logger.event('provider.tool_started', {
+                ...commonEventData(event),
+                ...(event.toolName ? { toolName: event.toolName } : {}),
+                ...(event.itemId !== undefined ? { itemId: event.itemId } : {}),
+            });
+            break;
+        case 'tool_progress':
+            await logger.event('provider.tool_progress', {
+                ...commonEventData(event),
+                ...(event.toolName ? { toolName: event.toolName } : {}),
+                ...(event.itemId !== undefined ? { itemId: event.itemId } : {}),
+                ...(event.message ? { message: event.message } : {}),
+                ...(event.isError ? { isError: event.isError } : {}),
+            });
+            break;
+        case 'command_completed': {
+            const cwd = event.cwd ?? options.cwd;
+            const gitHead = event.gitHead ?? await getGitHeadOrNull(cwd);
+            await logger.event('provider.command_completed', {
+                ...commonEventData(event),
+                ...(event.itemId !== undefined ? { itemId: event.itemId } : {}),
+                command: event.command,
+                ...(event.status !== undefined ? { status: event.status } : {}),
+                ...(event.exitCode !== undefined ? { exitCode: event.exitCode } : {}),
+                outputLength: event.outputLength ?? Buffer.byteLength(event.output ?? '', 'utf8'),
+                cwd,
+                gitHead,
+            });
+            break;
+        }
+        case 'file_changed':
+            await logger.event('provider.file_changed', {
+                ...commonEventData(event),
+                files: event.files,
+            });
+            break;
+        case 'assistant_text':
+            await logger.event('provider.assistant_text', {
+                ...commonEventData(event),
+                text: event.text,
+            });
+            break;
+        case 'assistant_thinking':
+            await logger.event('provider.assistant_thinking', {
+                ...commonEventData(event),
+                ...(event.estimatedTokens !== undefined ? { estimatedTokens: event.estimatedTokens } : {}),
+            });
+            break;
+        case 'structured_output_received':
+            await logger.event('provider.structured_output_received', commonEventData(event));
+            break;
+        case 'usage_reported':
+            await logger.event('provider.usage_reported', {
+                ...commonEventData(event),
+                usage: event.usage,
+            });
+            break;
+        case 'provider_error':
+            await logger.event('provider.provider_error', {
+                ...commonEventData(event),
+                message: event.message,
+                ...(event.errorKind ? { errorKind: event.errorKind } : {}),
+            });
+            break;
+    }
+}
+function renderDetail(event, logger) {
+    const context = {
+        provider: event.provider,
+        role: detailRole(event),
+    };
+    switch (event.type) {
+        case 'session_started':
+            writeDetail(`${detailPrefix(event)} thread ${event.sessionHandle}\n`, logger, context);
+            break;
+        case 'tool_progress':
+            if (!event.message) {
+                break;
+            }
+            if (event.isError) {
+                const message = event.message.endsWith('\n') ? event.message : `${event.message}\n`;
+                writeErrorDetail(`${detailPrefix(event)} ${message}`, logger, context);
+            }
+            else {
+                writeDetail(`${detailPrefix(event)} ${event.message}\n`, logger, context);
+            }
+            break;
+        case 'command_completed':
+            writeDetail(`\n$ ${event.command}\n${detailPrefix(event)} command ${event.status ?? 'completed'} (${formatExitCode(event.exitCode)}, ${event.outputLength ?? Buffer.byteLength(event.output ?? '', 'utf8')} output bytes)\n`, logger, {
+                ...context,
+                commandSummary: event.command,
+            });
+            if (event.output) {
+                writeDetail(`${event.output}\n`, logger, {
+                    ...context,
+                    commandSummary: event.command,
+                });
+            }
+            break;
+        case 'file_changed':
+            writeDetail(`${detailPrefix(event)} files ${event.files.join(', ')}\n`, logger, {
+                ...context,
+                fileCount: event.files.length,
+            });
+            break;
+        case 'assistant_text':
+            writeDetail(`${detailPrefix(event)} ${event.text}\n`, logger, context);
+            break;
+        case 'assistant_thinking':
+            writeDetail(`${detailPrefix(event)} thinking${typeof event.estimatedTokens === 'number' ? ` (~${event.estimatedTokens} tokens)` : ''}\n`, logger, context);
+            break;
+        case 'turn_completed': {
+            const subtype = event.providerData?.subtype;
+            if (typeof subtype === 'string' && subtype.trim()) {
+                writeDetail(`${detailPrefix(event)} result: ${subtype}\n`, logger, context);
+            }
+            break;
+        }
+        case 'provider_error':
+            writeErrorDetail(`${errorDetailPrefix(event)} ${event.message}\n`, logger, context);
+            break;
+        case 'turn_started':
+        case 'tool_started':
+        case 'structured_output_received':
+        case 'usage_reported':
+            break;
+    }
+}
+export function createProviderTelemetrySink(options) {
+    return async (event) => {
+        const resolvedEvent = {
+            ...event,
+            provider: event.provider ?? options.provider,
+            role: event.role ?? options.role,
+            label: event.label ?? options.label,
+        };
+        renderDetail(resolvedEvent, options.logger);
+        await writeRunEvent(resolvedEvent, options);
+    };
+}

package/dist/neal/providers/types.js

@@ -0,0 +1,21 @@
+export class NealProviderError extends Error {
+    provider;
+    role;
+    sessionHandle;
+    kind;
+    retryable;
+    cause;
+    constructor(args) {
+        super(args.message);
+        this.name = 'NealProviderError';
+        this.provider = args.provider;
+        this.role = args.role;
+        this.sessionHandle = args.sessionHandle ?? null;
+        this.kind = args.kind ?? 'unknown';
+        this.retryable = args.retryable ?? false;
+        this.cause = args.cause;
+    }
+}
+export function isNealProviderError(error) {
+    return error instanceof NealProviderError;
+}

package/dist/neal/recovery-artifacts.js

@@ -0,0 +1,50 @@
+import { formatPublicPhase } from './phase-display.js';
+function summarizeTurn(record, turn) {
+    const lines = [
+        `- Turn ${turn.number} guidance: ${turn.operatorGuidance}`,
+    ];
+    if (turn.disposition) {
+        lines.push(`- Turn ${turn.number} coder action: ${turn.disposition.action}`, `- Turn ${turn.number} coder summary: ${turn.disposition.summary}`, `- Turn ${turn.number} resulting step: ${formatPublicPhase(turn.disposition.resultingPhase)}`);
+    }
+    else if (turn.number <= record.lastHandledTurn) {
+        lines.push(`- Turn ${turn.number} coder response: handled without a persisted disposition summary`);
+    }
+    else {
+        lines.push(`- Turn ${turn.number} coder response: pending`);
+    }
+    return lines;
+}
+export function summarizeInteractiveBlockedRecoveryHistory(history) {
+    if (history.length === 0) {
+        return null;
+    }
+    const latest = history.at(-1) ?? null;
+    return {
+        sessions: history.length,
+        lastAction: latest?.resolvedByAction ?? null,
+        lastResultPhase: latest?.resultPhase ?? null,
+        lastBlockedReason: latest?.blockedReason ?? null,
+        lastOperatorGuidance: latest?.turns.at(-1)?.operatorGuidance ?? null,
+        lastCoderSummary: latest?.turns.at(-1)?.disposition?.summary ?? null,
+    };
+}
+export function renderInteractiveBlockedRecoveryHistoryLines(history, heading = '## Interactive Blocked Recovery History') {
+    if (history.length === 0) {
+        return [];
+    }
+    const lines = ['', heading];
+    for (const [index, record] of history.entries()) {
+        lines.push(`### Recovery Session ${index + 1}`, `- Source step: ${formatPublicPhase(record.sourcePhase)}`, `- Blocked reason: ${record.blockedReason}`, `- Turns used: ${record.turns.length}/${record.maxTurns}`, `- Resolved at: ${record.resolvedAt}`, `- Resolution: ${record.resolvedByAction}`, `- Result step: ${formatPublicPhase(record.resultPhase)}`);
+        if (record.pendingDirective) {
+            lines.push(`- Pending directive at resolution: ${record.pendingDirective.operatorGuidance}`);
+        }
+        if (record.turns.length === 0) {
+            lines.push('- Operator guidance: none recorded');
+            continue;
+        }
+        for (const turn of record.turns) {
+            lines.push(...summarizeTurn(record, turn));
+        }
+    }
+    return lines;
+}