import { WorktreeAdapter } from '@tangle-network/agent-eval/campaign';
import { Scenario, SelfImproveOptions, SurfaceProposer, SelfImproveResult, MutableSurface } from '@tangle-network/agent-eval/contract';
import { AgentProfile } from '@tangle-network/agent-interface';
import { L as LocalHarness } from './local-harness-ZLMkKdZc.js';
import { V as Verifier, C as CandidateGenerator } from './agentic-generator-1g7GDba7.js';

/**
 *
 * `improve` — the ONE public, surface-pluggable RSI verb.
 *
 * A thin facade over agent-eval's `selfImprove` (the held-out-gated closed
 * loop). It removes the two things a caller otherwise has to know to drive the
 * loop by hand: WHICH `MutableSurface` of the profile is being optimized, and
 * WHICH `SurfaceProposer` mutates that surface. You name a `surface`; the
 * facade picks the matching default proposer, extracts the baseline surface from
 * the profile, runs `selfImprove`, and (on a ship verdict) writes the promoted
 * winner back into the corresponding profile field.
 *
 *   - `surface: 'prompt'` → `gepaProposer` mutates `profile.prompt.systemPrompt`.
 *   - `surface: 'skills'` → `skillOptProposer` mutates a skills document string.
 *   - `surface: 'memory'` → `memoryCurationProposer` curates a bounded durable
 *     lesson document supplied through `opts.memory`.
 *   - `surface: 'agent-profile'` → caller-supplied proposer mutates the complete
 *     canonical AgentProfile JSON in one candidate.
 *   - `surface` ∈ {`tools`, `mcp`, `hooks`, `subagents`, `agent-profile`} → no zero-config default
 *     proposer exists (a code/config proposer needs caller-supplied wiring — a
 *     worktree repo root, a candidate generator, a serializer). The facade
 *     requires an explicit `opts.generator` for these and throws a `ConfigError`
 *     otherwise. This is a designed boundary, not a missing default: there is
 *     no safe value the facade could invent for those surfaces. Code instead
 *     requires `opts.code.repoRoot` and accepts only the runtime-owned
 *     `opts.code.generator` path so every isolated checkout can be released.
 *
 * Everything else (`scenarios`, `judge`, `agent`, `budget`, `llm`) passes
 * straight through to `selfImprove`.
 *
 * @experimental
 */

/** The executable agent lever `improve` optimizes. Profile fields remain
 *  portable AgentProfile coordinates; implementation and orchestration files
 *  use the code surface so a winner can be sealed into an exact candidate. */
type ImproveSurface = 'prompt' | 'skills' | 'tools' | 'mcp' | 'hooks' | 'subagents' | 'agent-profile' | 'memory' | 'code';
type ImproveOptions<TScenario extends Scenario, TArtifact> = Omit<SelfImproveOptions<TScenario, TArtifact>, 'analyzeGeneration' | 'baselineSurface' | 'findings' | 'gate' | 'proposer'> & {
    /** Which profile lever to optimize. Default `'prompt'`. Selects the default
     *  generator + the baseline-surface extraction shape. */
    surface?: ImproveSurface;
    /** The `SurfaceProposer` that mutates a profile surface. When unset, the facade
     *  picks the default for prompt, skills, and memory; surfaces
     *  with no default REQUIRE this (fail-loud otherwise). Forbidden for code;
     *  use `code.generator` so the runtime owns candidate cleanup. */
    generator?: SurfaceProposer;
    /** Gate mode. `'holdout'` (default) runs the held-out promotion gate;
     *  `'none'` is a baseline-only run (`budget.generations = 0`). */
    gate?: 'holdout' | 'none';
    /** Restrict the run to this subset of models. When set, the reflection model
     *  (`llm.model`, or the default when unset) must be a member, or `improve()` throws
     *  a `ConfigError` before the generator is built. Unset = unrestricted. */
    allowedModels?: readonly string[];
    /** Per-generation findings producer passthrough (see selfImprove.analyzeGeneration).
     *  DEFAULT: the built-in failure distiller — after each generation it turns the
     *  worst-scoring/errored cells into structured findings ({ scenario, composite,
     *  notes, error }) for the NEXT proposal round, so the proposer reasons over what
     *  actually failed instead of a static seed. Pass your own producer (e.g. a
     *  trace-analyst over the runDir's traces) to replace it; pass `null` to disable
     *  and keep the static `findings` all the way through. */
    analyzeGeneration?: SelfImproveOptions<TScenario, TArtifact>['analyzeGeneration'] | null;
    /** META-HARNESS mode: instead of the ~400-char distilled findings, feed the
     *  proposer RAW-TRACE FILESYSTEM CONTEXT — the PATHS into the prior generation's
     *  real run traces under `runDir` (per-cell `spans.jsonl` event logs +
     *  `cached-result.json` scores + artifacts) plus a `grep`/`cat`-to-diagnose
     *  instruction — so the coding agent reads the actual failures itself rather than
     *  a pre-summary. Requires a REAL `runDir` (that is where the traces live).
     *  Ignored when `analyzeGeneration` is set explicitly (that wins) or is `null`
     *  (disabled). Equivalent to `analyzeGeneration: rawTraceDistiller()`; this flag
     *  is the one-line enable. Default `false` (the distiller stays the default). */
    rawTraceContext?: boolean;
    /** CODE-surface wiring: name `surface: 'code'`, point at a repo, and the
     *  facade assembles the whole candidate pipeline — an isolated incumbent plus git worktrees
     *  (`gitWorktreeAdapter`) driven by `improvementDriver` with the full agentic
     *  generator (a real coding harness edits each candidate worktree; a `verify`
     *  hook gates candidates before they are ever measured). Ignored when
     *  `opts.generator` is supplied. Required for every code run because a real
     *  repository and base ref are necessary to measure the incumbent. */
    code?: ImproveCodeOptions;
    /** SKILLS-surface wiring for real skill-DOCUMENT optimization. Without this,
     *  `surface: 'skills'` optimizes the profile's skills REFS array (file pointers)
     *  — which `skillOptProposer` (a document patcher) cannot meaningfully edit.
     *  Provide the document CONTENT to optimize + a `writeBack` to persist the
     *  shipped winner (the profile ref points at a file the caller owns). This is
     *  what makes skillOpt reachable through improve(). */
    skills?: ImproveSkillsOptions;
    /** MEMORY-surface wiring for a curated durable memory document. The default
     *  deterministic proposer deduplicates and ranks lessons from findings, then
     *  replaces its managed block instead of growing memory without bound. */
    memory?: ImproveMemoryOptions;
    /** Custom held-back-exam decision. The string `gate` above controls whether
     *  the exam runs; this callback controls how its evidence decides promotion. */
    promotionGate?: SelfImproveOptions<TScenario, TArtifact>['gate'];
};
interface ImproveSkillsOptions {
    /** The skill document's current text — the baseline `skillOptProposer` patches. */
    document: string;
    /** Persist the shipped winner document (write the file the profile ref points at).
     *  Called only on a ship verdict. When omitted, the winner is still returned in
     *  `result.raw.winner.surface` for the caller to materialize. */
    writeBack?: (winnerDocument: string) => void | Promise<void>;
}
interface ImproveMemoryOptions {
    /** Current durable memory text used as the measured baseline. */
    document: string;
    /** Persist the promoted memory document. Never called on hold or error. */
    writeBack?: (winnerDocument: string) => void | Promise<void>;
}
interface ImproveCodeOptions {
    /** Repo root candidate worktrees fork from. */
    repoRoot: string;
    /** Base ref candidates fork from. Default `main`. */
    baseRef?: string;
    /** Directory worktrees are created under. Default `<repoRoot>/.worktrees`. */
    worktreeDir?: string;
    /** Git-compatible adapter override, primarily for tests. Candidate advancement
     *  still requires normal Git worktree and commit semantics. */
    worktree?: WorktreeAdapter;
    /** Coding harness the agentic generator runs in each worktree. Default `claude`. */
    harness?: LocalHarness;
    /** Verify a candidate worktree before it becomes a measurable surface; failures
     *  feed the next shot (see `agenticGenerator.verify` / `commandVerifier`). */
    verify?: Verifier;
    /** Per-shot wall-clock timeout for the harness (ms). */
    timeoutMs?: number;
    /** Byte-producer override — the test seam and the escape hatch for custom
     *  candidate production. When set, `harness`/`verify`/`timeoutMs` are unused. */
    generator?: CandidateGenerator;
}
interface ImproveResult<TScenario extends Scenario, TArtifact> {
    /** The profile after improvement: the winner surface applied back into the
     *  matching field when the gate shipped, else the input profile unchanged. */
    profile: AgentProfile;
    /** True when `gateDecision === 'ship'`. */
    shipped: boolean;
    /** Held-out lift (`winner − baseline` composite). */
    lift: number;
    /** The five-valued gate verdict from `selfImprove`. */
    gateDecision: SelfImproveResult<TScenario, TArtifact>['gateDecision'];
    /** Full `selfImprove` result for advanced inspection. For code runs,
     *  `raw.winner.surface.worktreeRef` remains live after return whether the
     *  candidate shipped or held; call `dispose()` after consuming it. */
    raw: SelfImproveResult<TScenario, TArtifact>;
    /** Release resources owned by this result. Idempotent; currently disposes
     *  the returned code worktree and is a no-op for profile-only surfaces. */
    dispose(): Promise<void>;
}
/** Apply a promoted winner surface back into the profile field for `surface`.
 *  Returns a shallow copy; never mutates the input profile. */
declare function applyImprovementWinnerToProfile(profile: AgentProfile, surface: ImproveSurface, winner: MutableSurface): AgentProfile;
/**
 * Run the held-out-gated self-improvement loop on ONE profile surface.
 *
 * @example Optimize the system prompt, default holdout gate:
 *
 *   const out = await improve(profile, findings, {
 *     surface: 'prompt',
 *     scenarios,
 *     judge,
 *     agent: (surface, scenario, ctx) => runAgent(surface, scenario, ctx.signal),
 *   })
 *   if (out.shipped) deploy(out.profile)
 */
declare function improve<TScenario extends Scenario, TArtifact>(profile: AgentProfile, findings: unknown[], opts: ImproveOptions<TScenario, TArtifact>): Promise<ImproveResult<TScenario, TArtifact>>;

export { type ImproveSurface as I, type ImproveOptions as a, type ImproveResult as b, type ImproveCodeOptions as c, type ImproveMemoryOptions as d, type ImproveSkillsOptions as e, applyImprovementWinnerToProfile as f, improve as i };
