import { z } from 'zod';
import { type HarnessProtectionPlan } from '../../eval/harness-protection.js';
import { type HarnessReview, type HarnessVerificationBatch } from '../../eval/harness-verification.js';
import type { DiskResidentAgenda } from './agenda.js';
import { type ResidentLearningEvidence, type ResidentSkillCandidate } from './learning.js';
/** @experimental One explicitly requested experiment; callbacks own inference and evaluation. */
export type ResidentLearningStage = 'explore' | 'generate' | 'verification' | 'confirmation';
declare const receiptSchema: z.ZodObject<{
    /** The session and turn of the execution this usage belongs to; one receipt per turn. */
    sessionId: z.ZodString;
    turnId: z.ZodString;
    tokens: z.ZodNullable<z.ZodNumber>;
    costUsd: z.ZodNullable<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
    sessionId: string;
    turnId: string;
    tokens: number | null;
    costUsd: number | null;
}, {
    sessionId: string;
    turnId: string;
    tokens: number | null;
    costUsd: number | null;
}>;
/** @experimental One non-overlapping execution's usage, including its retries. Null is unknown. */
export type ResidentLearningReceipt = Readonly<z.infer<typeof receiptSchema>>;
/** @experimental Recorded values are lower bounds when a receipt or stage is incomplete. */
export interface ResidentLearningConsumption {
    readonly tokens: number;
    readonly costUsd: number;
    readonly receipts: number;
    readonly unknownTokens: number;
    readonly unknownCosts: number;
    readonly unfinishedStages: number;
}
/** @experimental Append in sequence to host-owned durable storage before acknowledging. */
export interface ResidentLearningCycleEvent {
    readonly cycleId: string;
    readonly sequence: number;
    readonly kind: 'started' | 'stage-started' | 'stage-finished' | 'usage' | 'exploration' | 'candidate' | 'evaluation' | 'activation-requested' | 'finished';
    readonly stage?: ResidentLearningStage;
    readonly data: Readonly<Record<string, unknown>>;
}
/** @experimental Use this stage's signal for every owned execution; await every usage append. */
export interface ResidentLearningCycleContext {
    readonly cycleId: string;
    readonly stage: ResidentLearningStage;
    readonly signal: AbortSignal;
    /** Planning allowance, not a reservation or a cap on a callback's in-flight work. */
    readonly remainingUnits: number;
    recordUsage(receipt: ResidentLearningReceipt): Promise<void>;
}
/** @experimental Original failure and active baseline; never contains confirmation tasks. */
export interface ResidentLearningExplorationContext extends ResidentLearningCycleContext {
    readonly skillName: string;
    /** Admitted by the host before generation; cannot be changed by a candidate. */
    readonly purpose?: 'task' | 'exploration';
    readonly failure: Readonly<{
        evidence: ResidentLearningEvidence;
        trace: string;
    }>;
    readonly baseline: ResidentSkillCandidate | null;
}
/** @experimental Host-retained environment observations, not a model's claim of success. */
export interface ResidentLearningExploration {
    readonly evidence: ResidentLearningEvidence;
    readonly trace: string;
}
/** @experimental Generation sees completed exploration, never held-out evaluation cases. */
export interface ResidentLearningGenerationContext extends ResidentLearningExplorationContext {
    readonly exploration?: Readonly<ResidentLearningExploration>;
}
/** @experimental The host supplies independently scored, retained traces for these exact revisions. */
export interface ResidentLearningEvaluationContext extends ResidentLearningCycleContext {
    readonly baseline: ResidentSkillCandidate | null;
    readonly candidate: ResidentSkillCandidate;
    readonly baselineRevision: string;
    readonly candidateRevision: string;
}
/** @experimental No provider, default background loop or executable-code activation is installed. */
export interface ResidentLearningCycleOptions {
    /** Omitted means task guidance. Explicitly select exploration to improve an explorer policy. */
    readonly purpose?: 'task' | 'exploration';
    /** Fixed before generation; both rounds must preserve every named task. */
    readonly protection: HarnessProtectionPlan;
    readonly agenda: Pick<DiskResidentAgenda, 'read' | 'promoteSkill'>;
    readonly skillName: string;
    readonly failure: {
        readonly evidence: ResidentLearningEvidence;
        readonly trace: string;
    };
    readonly parentCycleId?: string;
    readonly signal: AbortSignal;
    /** Stops subsequent stages/activation after observed excess; callbacks enforce in-flight limits. */
    readonly resources: {
        readonly unit: 'tokens' | 'usd';
        readonly maxUnits: number;
    };
    readonly record: (event: ResidentLearningCycleEvent) => Promise<void>;
    /** Optional active tool exploration before synthesis; the host retains actual observations. */
    readonly explore?: (context: ResidentLearningExplorationContext) => Promise<{
        readonly observations: ResidentLearningExploration;
        readonly usageComplete: boolean;
    }>;
    readonly generate: (context: ResidentLearningGenerationContext) => Promise<{
        readonly candidate: ResidentSkillCandidate;
        /** All executions, including failures and side calls, have supplied receipts. */
        readonly usageComplete: boolean;
    }>;
    readonly evaluate: (context: ResidentLearningEvaluationContext) => Promise<{
        readonly batch: HarnessVerificationBatch;
        readonly usageComplete: boolean;
    }>;
}
/** @experimental An ambiguous activation must be inspected, never automatically replayed. */
export interface ResidentLearningCycleResult {
    readonly cycleId: string;
    readonly status: 'activated' | 'rejected' | 'inconclusive' | 'conflict' | 'cancelled' | 'failed' | 'activation-unknown';
    readonly reason: string;
    readonly candidate?: ResidentSkillCandidate;
    readonly candidateRevision?: string;
    readonly baselineRevision?: string;
    readonly agendaRevision?: number;
    readonly review?: HarnessReview;
    readonly consumption: ResidentLearningConsumption;
    readonly auditComplete: boolean;
}
/**
 * @experimental Generate one candidate, independently verify and confirm it, then
 * activate through the existing exact-revision transaction. No internal inference
 * loop, retry or model-generated success claim replaces the host's evaluator.
 */
export declare function runResidentLearningCycle(options: ResidentLearningCycleOptions): Promise<ResidentLearningCycleResult>;
export {};
//# sourceMappingURL=learning-cycle.d.ts.map