/**
 * Placement — one model for "where does the body run?"
 *
 * The CLI grew several doors that all mean execution target:
 *   run --device / --lease / --box / --cloud
 *   routines --placement / --run-on / hostStrategy
 *   monitors --run-on (body) vs --device (owner — NOT placement)
 *   teams --device (teammate pin)
 *   cloud run --provider host
 *
 * This module is the shared vocabulary. Old flags remain; --where is a
 * thin alias on `agents run` that expands into them. Docs and help teach
 * the matrix; stores stay separate (device registry, lease boxes, cloud).
 *
 * Owner (who may fire / evaluate) is NOT placement — see monitors.
 */
/** Where a job body executes. */
export type PlacementKind = 'local' | 'device' | 'fleet' | 'cloud' | 'lease';
/**
 * Canonical placement object.
 *
 *   kind: local  — this machine
 *   kind: device — named box or affinity pick (target: name | "auto")
 *   kind: fleet  — pick one online device at fire time (routines)
 *   kind: cloud  — vendor cloud dispatch
 *   kind: lease  — disposable crabbox (target: optional backend)
 */
export interface Placement {
    kind: PlacementKind;
    /** Device/host name, "auto", lease backend, or undefined. */
    target?: string;
    /** Flag or path that produced this (errors / diagnostics). */
    source: string;
}
/** Run-flag bag the placement parser understands. */
export interface RunPlacementFlags {
    where?: string;
    host?: string;
    device?: string;
    on?: string;
    computer?: string;
    lease?: string | boolean;
    box?: string;
    /** --cloud: vendor cloud placement (the agent's native cloud provider). */
    cloud?: boolean;
    /** --provider: refines the cloud placement; not a placement on its own. */
    provider?: string;
}
export declare class PlacementError extends Error {
    constructor(message: string);
}
/**
 * Parse a `--where` / placement spec string.
 *
 * Accepted forms:
 *   local
 *   device[:name] | host[:name]   (bare name → device:<name>)
 *   device:auto | auto | host:auto
 *   fleet
 *   cloud
 *   lease[:backend]
 */
export declare function parseWhereSpec(raw: string, source?: string): Placement;
/** First non-empty host-family flag value (host / device / on / computer). */
export declare function hostFamilyTarget(flags: RunPlacementFlags): string | undefined;
/**
 * Resolve placement from run flags. `--where` wins only when no other
 * placement flag is set; mixing is a PlacementError.
 */
export declare function placementFromRunFlags(flags: RunPlacementFlags): Placement;
/**
 * Expand a resolved placement into the concrete run option fields the
 * existing dispatch paths already understand. Pure — does not mutate input.
 *
 * `fleet` is not valid for a bare `agents run` (it is a routines placement);
 * it throws so callers fail loud.
 */
export declare function expandPlacementToRunFlags(placement: Placement): Pick<RunPlacementFlags, 'host' | 'device' | 'lease' | 'box' | 'cloud' | 'provider'>;
/** Map routines hostStrategy (+ optional host) onto the shared Placement. */
export declare function placementFromHostStrategy(strategy: 'local' | 'host' | 'fleet' | 'cloud', host?: string): Placement;
/** One-line human form for logs / help. */
export declare function formatPlacement(p: Placement): string;
/**
 * Short matrix for help footers and docs. Keep in sync with concepts.md.
 */
export declare const PLACEMENT_MATRIX: string;
