/**
 * Request normalizer for the Ricky local/BYOH entrypoint.
 *
 * Accepts spec handoff from CLI, MCP, Claude-style structured handoff,
 * or workflow artifact path and normalizes into one local invocation
 * request contract.
 */
import type { RunRetryMetadata } from '../runtime/types.js';
export type HandoffSource = 'free-form' | 'structured' | 'cli' | 'mcp' | 'claude' | 'workflow-artifact';
export type LocalExecutionMode = 'local' | 'cloud' | 'both';
export type LocalExecutionPreference = LocalExecutionMode | 'auto';
export type LocalStageMode = 'generate' | 'run' | 'generate-and-run';
export type StructuredSpec = Record<string, unknown>;
export type SpecInput = string | StructuredSpec;
export interface LocalSourceMetadata {
    cli?: Record<string, unknown>;
    mcp?: Record<string, unknown>;
    claude?: Record<string, unknown>;
}
export interface BaseHandoff {
    /** Preferred execution target. `mode` is kept as the stable shorthand. */
    mode?: LocalExecutionMode | LocalStageMode;
    /** Whether a generated artifact should stop at generation or continue into local runtime. */
    stageMode?: LocalStageMode;
    /** Alias accepted by CLI/API callers that model the choice as behavior rather than stage. */
    behavior?: LocalStageMode;
    /**
     * Real caller root captured at the invocation boundary.
     * Used to keep generated artifact writes anchored to the user's repo even
     * when the CLI itself executes from a workspace package directory.
     */
    invocationRoot?: string;
    /**
     * Alias for `mode`. When both are set, `mode` takes priority (see `executionModeFor`).
     * Exists so callers that model the choice as a "preference" rather than a "mode"
     * can pass it naturally without mapping to the `mode` field.
     */
    executionPreference?: LocalExecutionPreference;
    metadata?: Record<string, unknown>;
    requestId?: string;
    /** Bounded local repair loop. Undefined means one attempt with current behavior. */
    autoFix?: {
        maxAttempts: number;
    };
    /** Retry metadata supplied by an orchestrator wrapping local execution. */
    retry?: Partial<RunRetryMetadata>;
    /** Optional LLM refinement request for generated workflow artifacts. */
    refine?: false | {
        model?: string;
    };
    /**
     * Let Ricky resolve blocking spec clarifications with conservative implementer
     * assumptions instead of asking the user before generation.
     */
    bestJudgement?: boolean;
}
/** Free-form spec string from a direct local caller. */
export interface FreeFormSpecHandoff extends BaseHandoff {
    source: 'free-form';
    spec: string;
}
/** Structured spec object from a direct local caller. */
export interface StructuredSpecHandoff extends BaseHandoff {
    source: 'structured';
    spec: StructuredSpec;
}
/** Free-form spec string passed via CLI (--spec flag or stdin). */
export interface CliHandoff extends BaseHandoff {
    source: 'cli';
    spec: SpecInput;
    specFile?: string;
    cliMetadata?: Record<string, unknown>;
}
/** Structured MCP tool invocation payload (ricky.generate). */
export interface McpHandoff extends BaseHandoff {
    source: 'mcp';
    spec?: SpecInput;
    toolName?: string;
    arguments?: Record<string, unknown>;
    mcpMetadata?: Record<string, unknown>;
}
/** Claude-style structured handoff with optional conversation context. */
export interface ClaudeHandoff extends BaseHandoff {
    source: 'claude';
    spec: SpecInput;
    conversationId?: string;
    turnId?: string;
}
/** Reference to an existing workflow artifact on disk. */
export interface WorkflowArtifactHandoff extends BaseHandoff {
    source: 'workflow-artifact';
    artifactPath: string;
}
export type RawHandoff = FreeFormSpecHandoff | StructuredSpecHandoff | CliHandoff | McpHandoff | ClaudeHandoff | WorkflowArtifactHandoff;
export interface LocalInvocationRequest {
    /**
     * Discriminator field that distinguishes a normalized request from a raw
     * handoff at runtime. Raw handoffs never carry this field, so
     * `isLocalInvocationRequest()` can rely on it instead of heuristic
     * structural checks that overlap with raw handoff shapes.
     */
    _normalized: true;
    /** The spec content (inline or resolved from artifact path). */
    spec: string;
    /** Structured spec payload when the source supplied one. */
    structuredSpec?: StructuredSpec;
    /** Where the handoff originated. */
    source: HandoffSource;
    /**
     * Execution mode — defaults to 'local' for BYOH.
     * Callers that pass `executionPreference` on the handoff input get it
     * resolved here (see `executionModeFor`), so downstream code only needs
     * to inspect `mode`.
     */
    mode: LocalExecutionMode;
    /** Normalized execution preference as supplied by CLI/MCP/Claude-style callers. */
    executionPreference?: LocalExecutionPreference;
    /** Product-stage behavior. Undefined preserves legacy executor behavior for direct callers. */
    stageMode?: LocalStageMode;
    /** Caller repo root captured at the CLI boundary when available. */
    invocationRoot?: string;
    /** Optional file path when the spec came from a file or artifact. */
    specPath?: string;
    /** Opaque metadata from the originating surface. */
    metadata: Record<string, unknown>;
    /** Surface-specific metadata preserved without flattening. */
    sourceMetadata?: LocalSourceMetadata;
    /** Stable request id when the caller supplied one. */
    requestId?: string;
    /** Bounded local repair loop. Undefined means one attempt with current behavior. */
    autoFix?: {
        maxAttempts: number;
    };
    /** Retry metadata supplied by an orchestrator wrapping local execution. */
    retry?: Partial<RunRetryMetadata>;
    /** Optional LLM refinement request for generated workflow artifacts. */
    refine?: false | {
        model?: string;
    };
    /** Resolve blocking clarification questions using implementer best judgement. */
    bestJudgement?: boolean;
}
export interface ArtifactReader {
    readArtifact(path: string): Promise<string>;
}
/**
 * Normalize any supported handoff shape into a single LocalInvocationRequest.
 *
 * - CLI and MCP handoffs carry the spec inline.
 * - Claude handoffs carry the spec inline with optional conversation context.
 * - Workflow artifact handoffs resolve the spec from disk via the injected reader.
 * - Mode defaults to 'local' — Cloud is never a hidden fallback.
 */
export declare function normalizeRequest(raw: RawHandoff, reader?: ArtifactReader): Promise<LocalInvocationRequest>;
