/**
 * Persona loading and translation.
 *
 * A persona is a JSON file that describes a pre-configured agent: which
 * harness (CLI) to use, which model, what system prompt to inject, plus
 * optional MCP servers and permission flags. Personas live in
 * `<cwd>/agentworkforce/personas`, the AgentWorkforce home directory, or
 * any directory the caller passes explicitly.
 *
 * Translation from a resolved persona to `{bin, args}` delegates to
 * `@agentworkforce/harness-kit#buildInteractiveSpec`, so relay always
 * produces the same launch args the AgentWorkforce CLI does.
 *
 * The schema mirrors the AgentWorkforce persona format
 * (see https://github.com/AgentWorkforce/workforce). Skills installation,
 * mount policy, sidecar markdown, input rendering, and routing profiles
 * are deliberately not handled here — callers needing those should use
 * the `agentworkforce` CLI directly.
 */
import { type InteractiveConfigFile } from '@agentworkforce/harness-kit';
import { HARNESS_VALUES, PERSONA_TIERS, type Harness, type McpServerSpec, type PersonaPermissions, type PersonaTier } from '@agentworkforce/workload-router';
export type { Harness, McpServerSpec, PersonaPermissions, PersonaTier };
export { HARNESS_VALUES, PERSONA_TIERS };
export interface PersonaTierSpec {
    harness?: Harness;
    model?: string;
    systemPrompt?: string;
    /** Free-form harness settings (reasoning level, timeout) — not consumed by spawnPty today. */
    harnessSettings?: Record<string, unknown>;
}
/** Raw persona file shape. */
export interface PersonaFile {
    id: string;
    intent?: string;
    description?: string;
    tags?: string[];
    /** Used for every tier when set without `tiers`. Ignored when `tiers` is set. */
    systemPrompt?: string;
    /** Top-level harness/model — used when there are no tiers. */
    harness?: Harness;
    model?: string;
    permissions?: PersonaPermissions;
    mcpServers?: Record<string, McpServerSpec>;
    /** Per-tier overrides. A tier set here takes precedence over the top-level fields. */
    tiers?: Partial<Record<PersonaTier, PersonaTierSpec>>;
    /** Inherits from another persona id (looked up in the same search dirs). One level deep. */
    extends?: string;
}
/** A persona file located on disk. */
export interface DiscoveredPersona {
    id: string;
    path: string;
    spec: PersonaFile;
}
/** A persona resolved against a tier — ready for {@link buildPersonaSpawnSpec}. */
export interface ResolvedPersona {
    id: string;
    /** Absolute path to the JSON file the spec came from. */
    source: string;
    tier: PersonaTier;
    harness: Harness;
    model: string;
    systemPrompt: string;
    description?: string;
    permissions?: PersonaPermissions;
    mcpServers?: Record<string, McpServerSpec>;
}
export interface PersonaLoadOptions {
    cwd?: string;
    /** Override the default search-dir cascade. */
    searchDirs?: string[];
    /** Extra dirs appended after the default cascade. */
    extraDirs?: string[];
    /** Tier to resolve. Defaults to 'best'. */
    tier?: PersonaTier;
}
/**
 * The shape `AgentRelay.spawnPersona` needs to drive `spawnPty`. Built by
 * {@link buildPersonaSpawnSpec} from a {@link ResolvedPersona}.
 */
export interface PersonaSpawnSpec {
    /** CLI to launch (matches relay's AgentCli union: 'claude' | 'codex' | 'opencode'). */
    cli: string;
    model: string;
    args: string[];
    /**
     * If non-null, append this as the final positional arg to the CLI invocation.
     * Codex uses this to carry the system prompt; claude / opencode return null.
     */
    initialPrompt: string | null;
    /**
     * Files the caller must materialize (relative to spawn cwd) before launching
     * the agent. Used by opencode to drop an `opencode.json` carrying the
     * persona's agent definition. Empty for claude / codex.
     */
    configFiles: InteractiveConfigFile[];
    /** Non-fatal warnings from the harness-kit translation step. */
    warnings: string[];
}
/**
 * The default cascade. First match wins for a given persona id.
 *
 * 1. `<cwd>/agentworkforce/personas`            (the path most projects pick)
 * 2. `<cwd>/.agentworkforce/workforce/personas` (workforce CLI's project default)
 * 3. `<cwd>/agentworkforce/workforce/personas`  (alt workforce layout)
 * 4. `$AGENT_WORKFORCE_HOME/personas` if set, else `~/.agentworkforce/workforce/personas`
 */
export declare function defaultPersonaSearchDirs(cwd?: string): string[];
/**
 * List every persona discoverable across the search-dir cascade. When the
 * same id appears in multiple dirs, only the first match (by cascade order)
 * is returned.
 */
export declare function listPersonas(options?: PersonaLoadOptions): DiscoveredPersona[];
/**
 * Find a persona file by id across the search-dir cascade.
 * Returns undefined if not found.
 */
export declare function findPersona(id: string, options?: PersonaLoadOptions): DiscoveredPersona | undefined;
/**
 * Load and resolve a persona by id. Searches the cascade, applies the
 * chosen tier, and resolves a single level of `extends` against the same
 * cascade. Throws if the persona is missing required fields for the tier.
 */
export declare function loadPersona(id: string, options?: PersonaLoadOptions): ResolvedPersona;
/**
 * Translate a resolved persona into the bin/args spawnPty needs. Delegates
 * to {@link buildInteractiveSpec} from `@agentworkforce/harness-kit` so
 * relay produces the same launch shape the AgentWorkforce CLI does.
 */
export declare function buildPersonaSpawnSpec(persona: ResolvedPersona): PersonaSpawnSpec;
/**
 * Codex has no system-prompt flag, so the persona's instructions must ride
 * on the task. Combines them in the same shape the agentworkforce
 * harness-kit uses for non-interactive codex runs.
 */
export declare function composePersonaTask(spec: Pick<PersonaSpawnSpec, 'initialPrompt'>, userTask: string | undefined): string | undefined;
/** Tracks a file we wrote, so the caller can restore the prior contents. */
export interface MaterializedConfigFile {
    /** Absolute path that was written. */
    path: string;
    /** Whether a file existed at this path before we wrote. */
    existed: boolean;
    /** Prior contents (only set when existed is true). */
    previous?: string;
}
/**
 * Write each persona config file into `cwd`. Refuses absolute paths or
 * paths that escape `cwd`. Returns handles the caller can pass to
 * {@link restorePersonaConfigFiles}.
 */
export declare function materializePersonaConfigFiles(cwd: string, files: readonly InteractiveConfigFile[]): MaterializedConfigFile[];
/**
 * Restore the original state of files written by
 * {@link materializePersonaConfigFiles}. Files that did not exist before
 * are removed; files that did exist are written back to their prior
 * contents. Errors are swallowed — restore is best-effort cleanup.
 */
export declare function restorePersonaConfigFiles(writes: readonly MaterializedConfigFile[]): void;
//# sourceMappingURL=personas.d.ts.map