/**
 * Ricky local/BYOH entrypoint.
 *
 * Ties together request normalization, spec intake, workflow generation,
 * and local runtime coordination. Returns artifacts, logs, warnings, and
 * suggested next actions — without routing through Cloud by default.
 */
import type { ArtifactReader, LocalInvocationRequest, RawHandoff } from './request-normalizer.js';
import type { GenerationInput } from '../product/generation/index.js';
import type { ClarificationQuestion } from '../product/spec-intake/index.js';
import type { CommandRunner, CoordinatorResult, ExecutionRoute, RunRequest } from '../runtime/types.js';
export interface LocalResponseArtifact {
    /** Path to the generated or consumed artifact (may be relative or absolute). */
    path: string;
    /** MIME type hint (e.g. 'text/typescript', 'application/json'). */
    type?: string;
    /** Artifact content when available inline. */
    content?: string;
}
export type LocalGenerationStatus = 'ok' | 'error' | 'needs_clarification';
export type LocalExecutionStatus = 'success' | 'blocker' | 'error';
export interface LocalAssistantTurnContextDecision {
    assistant_id: string;
    turn_id: string;
    adapter: string;
    package: string;
    context_blocks: string[];
    enrichment_ids: string[];
}
export interface BestJudgementClarificationDecision {
    question_id: string;
    question: string;
    answer: string;
    answered_by: string;
    mode: '--best-judgement';
}
export interface LocalGenerationStageResult {
    stage: 'generate';
    status: LocalGenerationStatus;
    artifact?: {
        path: string;
        workflow_id: string;
        spec_digest: string;
        target_files?: string[];
    };
    next?: {
        run_command: string;
        run_mode_hint: string;
    };
    error?: string;
    decisions?: {
        skill_matches?: unknown;
        tool_selection?: unknown;
        master_execution?: unknown;
        refinement?: unknown;
        workforce_persona?: unknown;
        clarification_questions?: ClarificationQuestion[];
        best_judgement_clarifications?: BestJudgementClarificationDecision[];
        assistant_turn_context?: LocalAssistantTurnContextDecision;
    };
}
export type LocalBlockerCode = 'MISSING_ENV_VAR' | 'MISSING_BINARY' | 'INVALID_ARTIFACT' | 'UNSUPPORTED_RUNTIME' | 'RUNTIME_HANDOFF_STALLED' | 'CREDENTIALS_REJECTED' | 'STEP_TIMEOUT' | 'WORKDIR_DIRTY' | 'NETWORK_UNREACHABLE' | 'NETWORK_TRANSIENT';
export type LocalBlockerCategory = 'environment' | 'credentials' | 'dependency' | 'workflow_invalid' | 'resource' | 'timeout' | 'unsupported';
export interface LocalClassifiedBlocker {
    code: LocalBlockerCode;
    category: LocalBlockerCategory;
    message: string;
    detected_at: string;
    detected_during: 'precheck' | 'launch' | 'step_setup';
    recovery: {
        actionable: boolean;
        steps: string[];
        docs_url?: string;
    };
    context: {
        missing: string[];
        found: string[];
    };
}
export interface LocalExecutionEvidence {
    outcome_summary: string;
    artifacts_produced?: Array<{
        path: string;
        kind: string;
        bytes: number;
    }>;
    failed_step?: {
        id: string;
        name: string;
    };
    exit_code?: number | null;
    logs: {
        stdout_path?: string;
        stderr_path?: string;
        tail?: string[];
        truncated: boolean;
    };
    side_effects: {
        files_written: string[];
        commands_invoked: string[];
        network_calls?: Array<{
            host: string;
            status_code: number;
        }>;
    };
    assertions: Array<{
        name: string;
        status: 'pass' | 'fail' | 'skipped';
        detail: string;
    }>;
    workflow_steps?: Array<{
        id: string;
        name: string;
        status: 'pass' | 'fail' | 'skipped';
        duration_ms: number;
    }>;
}
export interface LocalExecutionStageResult {
    stage: 'execute';
    status: LocalExecutionStatus;
    execution: {
        workflow_id: string;
        artifact_path: string;
        command: string;
        workflow_file: string;
        cwd: string;
        started_at: string;
        finished_at: string;
        duration_ms: number;
        steps_completed: number;
        steps_total: number;
        run_id?: string;
    };
    evidence?: LocalExecutionEvidence;
    blocker?: LocalClassifiedBlocker;
}
export interface LocalResponse {
    /** Whether the local invocation succeeded. */
    ok: boolean;
    /** Generated or consumed artifacts. */
    artifacts: LocalResponseArtifact[];
    /** Structured log entries from the local run. */
    logs: string[];
    /** Non-fatal warnings surfaced during execution. */
    warnings: string[];
    /** Suggested next actions for the user. */
    nextActions: string[];
    /** Structured questions Ricky needs answered before it can safely continue. */
    clarificationQuestions?: ClarificationQuestion[];
    /** Stage 1 result: artifact generation or artifact selection. */
    generation?: LocalGenerationStageResult;
    /** Stage 2 result: populated only when run behavior was requested. */
    execution?: LocalExecutionStageResult;
    /** Process-oriented exit code: 0 success, 2 blocker, 1 error. */
    exitCode?: 0 | 1 | 2;
    /** Auto-fix loop metadata when --auto-fix/--repair was requested. */
    auto_fix?: {
        max_attempts: number;
        attempts: Array<Record<string, unknown>>;
        final_status: 'ok' | 'blocker' | 'error';
        run_id?: string;
        resumed?: boolean;
        escalation?: {
            summary: string;
            log_tail: string[];
            options: Array<{
                label: string;
                description: string;
                command?: string;
            }>;
        };
    };
}
/**
 * The executor is the seam between the entrypoint and actual work.
 * Inject a fake in tests; wire the Relay SDK workflow runner in production.
 */
export interface LocalExecutor {
    /**
     * Run the local workflow generation and execution pipeline.
     * Receives the normalized request and returns the local response contract.
     */
    execute(request: LocalInvocationRequest): Promise<LocalResponse>;
}
export interface ArtifactWriter {
    writeArtifact(path: string, content: string, cwd: string): Promise<void>;
}
/**
 * Structural interface for the coordinator dependency.
 * Captures only the `launch` method that the local executor actually uses,
 * so external adapters can satisfy the contract without extending the
 * concrete `LocalCoordinator` class.
 */
export interface CoordinatorLauncher {
    launch(request: RunRequest): Promise<CoordinatorResult>;
}
export interface LocalExecutorOptions {
    cwd?: string;
    timeoutMs?: number;
    commandRunner?: CommandRunner;
    coordinator?: CoordinatorLauncher;
    artifactWriter?: ArtifactWriter;
    /** Override the default execution route for the local runtime. */
    route?: ExecutionRoute;
    /** Override the SDK-backed script workflow runner used by the default local route. */
    scriptWorkflowRunner?: ScriptWorkflowRunner;
    /** When true, stop after writing/generated artifact and return it without launching local runtime. */
    returnGeneratedArtifactOnly?: boolean;
    /** When true, persist generator metadata sidecars beside workflow runtime artifacts. Defaults to false. */
    persistGenerationMetadataArtifacts?: boolean;
    /** Optional Workforce persona writer integration for generated workflow artifacts. */
    workforcePersonaWriter?: false | Omit<NonNullable<GenerationInput['workforcePersonaWriter']>, 'repoRoot' | 'targetMode' | 'outputPath'>;
    /** Concise phase updates for foreground CLI progress indicators. */
    onProgress?: (message: string) => void;
    /** Foreground workflow runtime output stream, separate from Ricky progress. */
    onRuntimeOutput?: (stream: 'stdout' | 'stderr', line: string) => void;
}
export interface ScriptWorkflowRunnerOptions {
    cwd: string;
    env?: Record<string, string>;
    timeoutMs?: number;
    signal?: AbortSignal;
    startFrom?: string;
    previousRunId?: string;
    resume?: string;
    onStdout?: (line: string) => void;
    onStderr?: (line: string) => void;
}
export type ScriptWorkflowRunner = (workflowFile: string, options: ScriptWorkflowRunnerOptions) => Promise<unknown>;
/**
 * Default execution route for local runtime coordination. This names the
 * programmatic SDK script runner rather than the agent-relay CLI binary.
 */
export declare const DEFAULT_LOCAL_ROUTE: ExecutionRoute;
export declare function createProcessCommandRunner(): CommandRunner;
export declare function createSdkScriptWorkflowRunner(): ScriptWorkflowRunner;
export declare function createLocalExecutor(options?: LocalExecutorOptions): LocalExecutor;
export declare function getDefaultExecutor(): LocalExecutor;
/**
 * Reset the lazily-initialized default executor. Intended for test isolation
 * where a previous test may have constructed the singleton with stale options.
 * Production code should not need to call this.
 */
export declare function resetDefaultExecutor(): void;
export interface LocalEntrypointOptions {
    executor?: LocalExecutor;
    artifactReader?: ArtifactReader;
    localExecutor?: LocalExecutorOptions;
    onProgress?: (message: string) => void;
    onRuntimeOutput?: (stream: 'stdout' | 'stderr', line: string) => void;
}
export type LocalEntrypointInput = RawHandoff | LocalInvocationRequest;
/**
 * Main local/BYOH entrypoint.
 *
 * 1. Normalizes the raw handoff into a LocalInvocationRequest.
 * 2. Validates that the request is suitable for local execution.
 * 3. Delegates to the executor for generation + runtime coordination.
 * 4. Returns the unified local response contract.
 */
export declare function runLocal(handoff: LocalEntrypointInput, options?: LocalEntrypointOptions): Promise<LocalResponse>;
export declare function isExecutableWorkflowPath(path: string): boolean;
export declare function appendCoordinatorLogs(target: string[], result: CoordinatorResult): void;
