@unbrained/pm-cli 2026.9.3 → 2026.9.5

package/dist/sdk/environment/agent-environment.d.ts

@@ -0,0 +1,296 @@
+import { type WorkspaceRecipe } from "../workspace-recipe.js";
+/** Schema identifier for a portable observation contract. */
+export declare const PM_OBSERVATION_SCHEMA: "pm.agent-observation/v1";
+/** Schema identifier for a deterministic verdict contract. */
+export declare const PM_VERDICT_SCHEMA: "pm.agent-verdict/v1";
+/** Schema identifier for a bounded agent-environment episode. */
+export declare const PM_EPISODE_SCHEMA: "pm.agent-episode/v1";
+/** A JSON-compatible object used as immutable recorded workspace state. */
+export type RecordedStateObject = Readonly<Record<string, unknown>>;
+/** One declared read and its guaranteed token ceiling. */
+export interface ObservationReadDeclaration {
+    /** Public SDK or CLI command name used to collect the read. */
+    command: string;
+    /** Maximum tokens this read may consume. */
+    budget_tokens: number;
+}
+/** Emitted-byte calibration for a representative observation corpus. */
+export interface ObservationCalibration {
+    /** Stable measurement basis; serialized payload bytes are authoritative. */
+    basis: "emitted_bytes";
+    /** Historical emitted-byte measurements used to calibrate expectations. */
+    samples: readonly number[];
+    /** Expected serialized payload size before an observation is served. */
+    expected_emitted_bytes: number;
+    /** Accepted drift around the expected emitted-byte measurement. */
+    tolerance_bytes: number;
+}
+/** Declares whether observation cost varies with corpus size. */
+export type ObservationCorpusDependence = {
+    readonly kind: "independent";
+} | {
+    readonly kind: "bounded";
+    readonly dimension: string;
+    readonly maximum: number;
+};
+/** One ordered disclosure tier in an observation degradation ladder. */
+export interface ObservationTier {
+    /** Stable tier identity included in every observation receipt. */
+    id: string;
+    /** Maximum tokens this tier is permitted to emit. */
+    max_tokens: number;
+    /** Dot-separated recorded-state fields disclosed by the tier. */
+    fields: readonly string[];
+}
+/** Portable declaration for a bounded, calibrated observation. */
+export interface ObservationContract {
+    /** Versioned schema identity. */
+    schema: typeof PM_OBSERVATION_SCHEMA;
+    /** Stable contract identity. */
+    id: string;
+    /** Positive contract revision. */
+    version: number;
+    /** Reads whose ceilings form the guaranteed collection cost. */
+    reads: readonly ObservationReadDeclaration[];
+    /** Emitted-byte calibration visible before collection starts. */
+    calibration: ObservationCalibration;
+    /** Explicit corpus-size dependence of the cost model. */
+    corpus_dependence: ObservationCorpusDependence;
+    /** Ordered richest-to-smallest degradation ladder. */
+    tiers: readonly ObservationTier[];
+}
+/** Pre-call observation-cost description available to schedulers. */
+export interface ObservationCostDescription {
+    /** Stable observation identity. */
+    contract_id: string;
+    /** Observation revision. */
+    contract_version: number;
+    /** Sum of all declared collection ceilings. */
+    guaranteed_ceiling_tokens: number;
+    /** Calibrated expected serialized payload size. */
+    expected_emitted_bytes: number;
+    /** Conservative token estimate derived from emitted bytes. */
+    expected_tokens: number;
+    /** Accepted emitted-byte calibration drift. */
+    tolerance_bytes: number;
+    /** Stable calibration basis. */
+    calibration_basis: "emitted_bytes";
+    /** Declared corpus-size dependence. */
+    corpus_dependence: ObservationCorpusDependence;
+}
+/** Audit receipt emitted for every served or refused observation. */
+export interface ObservationReceipt {
+    /** Stable observation identity. */
+    contract_id: string;
+    /** Observation revision. */
+    contract_version: number;
+    /** Tier whose payload was returned, or null after truthful refusal. */
+    served_tier: string | null;
+    /** Whether a smaller tier was attempted or served. */
+    degraded: boolean;
+    /** Tier identities evaluated in deterministic order. */
+    attempted_tiers: readonly string[];
+    /** Exact serialized payload bytes, or null when nothing was served. */
+    emitted_bytes: number | null;
+    /** Conservative token estimate, or null when nothing was served. */
+    estimated_tokens: number | null;
+    /** Stable measurement basis. */
+    calibration_basis: "emitted_bytes";
+}
+/** Successful bounded observation with its explicit receipt. */
+export interface ServedObservation<T> {
+    /** Discriminator for a payload-bearing response. */
+    status: "served";
+    /** Payload produced by the declared tier. */
+    payload: T;
+    /** Cost and degradation evidence. */
+    receipt: ObservationReceipt;
+}
+/** Refusal returned when no declared tier can fit the caller's ceiling. */
+export interface RefusedObservation {
+    /** Discriminator for a payload-free refusal. */
+    status: "refused";
+    /** Stable reason callers can route without parsing prose. */
+    reason: "no_declared_tier_fits_budget";
+    /** Cost and degradation evidence. */
+    receipt: ObservationReceipt;
+}
+/** Complete outcome of attempting one declared observation. */
+export type ObservationResult<T> = ServedObservation<T> | RefusedObservation;
+/** Caller-imposed ceiling for one observation response. */
+export interface ObservationRequest {
+    /** Maximum response tokens accepted by the caller. */
+    budget_tokens: number;
+}
+/** Predicate supported by the versioned total-verdict interpreter. */
+export type VerdictPredicate = {
+    readonly id: string;
+    readonly kind: "field_equals";
+    readonly path: string;
+    readonly expected: unknown;
+} | {
+    readonly id: string;
+    readonly kind: "field_present";
+    readonly path: string;
+} | {
+    readonly id: string;
+    readonly kind: "field_absent";
+    readonly path: string;
+};
+/** Declarative composition applied to predicate outcomes. */
+export interface VerdictComposition {
+    /** Whether every or at least one referenced predicate must satisfy. */
+    operator: "all" | "any";
+    /** Ordered predicate identities evaluated by the total verdict. */
+    predicate_ids: readonly string[];
+}
+/** Portable named and versioned total-verdict declaration. */
+export interface VerdictContract {
+    /** Versioned schema identity. */
+    schema: typeof PM_VERDICT_SCHEMA;
+    /** Stable contract identity. */
+    id: string;
+    /** Positive contract revision. */
+    version: number;
+    /** Predicates evaluated exclusively over recorded state. */
+    predicates: readonly VerdictPredicate[];
+    /** Explicit deterministic predicate composition. */
+    composition: VerdictComposition;
+}
+/** Recorded state and stable snapshot identity supplied by an adapter. */
+export interface WorkspaceRecordedState {
+    /** Stable identity of the exact state being evaluated. */
+    snapshot_id: string;
+    /** Recorded, JSON-compatible project state. */
+    state: RecordedStateObject;
+}
+/** Per-predicate evidence in a deterministic total verdict. */
+export interface PredicateVerdict {
+    /** Declared predicate identity. */
+    id: string;
+    /** Whether the predicate is satisfied by recorded state. */
+    outcome: "satisfied" | "violated";
+    /** Snapshot-qualified JSON pointer to the inspected field. */
+    evidence_pointer: string;
+    /** Hash of the observed value without duplicating potentially private data. */
+    evidence_digest: string;
+}
+/** Total, reproducible result produced by a verdict contract. */
+export interface VerdictResult {
+    /** Stable verdict identity. */
+    contract_id: string;
+    /** Verdict revision. */
+    contract_version: number;
+    /** Exact recorded-state snapshot evaluated. */
+    snapshot_id: string;
+    /** Total outcome, including an explicit empty-contract state. */
+    outcome: "satisfied" | "violated" | "not_applicable";
+    /** Satisfied fraction, or null when no predicates are declared. */
+    score: number | null;
+    /** Explicitly separates evaluation from reward or learning signals. */
+    policy: "verdict_only_no_reward";
+    /** Stable explanation for a not-applicable verdict. */
+    reason?: "no_predicates_declared";
+    /** Ordered predicate evidence. */
+    predicates: readonly PredicateVerdict[];
+}
+/** Hard limits enforced within one isolated episode. */
+export interface EpisodeLimits {
+    /** Maximum ordinary project-management actions. */
+    max_actions: number;
+    /** Maximum observations, including the close-time grading read. */
+    max_observations: number;
+    /** Per-observation response ceiling. */
+    max_tokens_per_observation: number;
+}
+/** Portable specification shared by evaluation and training harnesses. */
+export interface EpisodeSpecification {
+    /** Versioned schema identity. */
+    schema: typeof PM_EPISODE_SCHEMA;
+    /** Stable episode identity and session provenance key. */
+    id: string;
+    /** Positive episode revision. */
+    version: number;
+    /** Consumer intent without coupling the runtime to a training framework. */
+    mode: "benchmark" | "evaluation" | "training" | "scale_transfer";
+    /** Deterministic workspace construction recipe. */
+    recipe: WorkspaceRecipe;
+    /** Canonical pm items that define the task set. */
+    task_item_ids: readonly string[];
+    /** State fields that observations may disclose. */
+    observable_fields: readonly string[];
+    /** Grading-only fields that must never enter observations. */
+    withheld_fields: readonly string[];
+    /** Bounded observation declaration. */
+    observation: ObservationContract;
+    /** Recorded-state verdict declaration. */
+    verdict: VerdictContract;
+    /** Hard action and observation limits. */
+    limits: EpisodeLimits;
+}
+/** Reset receipt returned by an episode adapter. */
+export interface EpisodeResetReceipt {
+    /** Adapter-defined isolated workspace identity. */
+    workspace_id: string;
+    /** Stable state identity after reset. */
+    state_id: string;
+}
+/** Action receipt returned by an episode adapter. */
+export interface EpisodeActionReceipt<TOutput> {
+    /** Stable state identity after the action. */
+    state_id: string;
+    /** Adapter-defined ordinary command result. */
+    output: TOutput;
+}
+/** Host boundary for ordinary pm SDK actions and recorded-state reads. */
+export interface EpisodeRuntimeAdapter<TAction, TOutput = unknown> {
+    /** Construct a fresh isolated workspace using the declared recipe. */
+    reset(recipe: WorkspaceRecipe): Promise<EpisodeResetReceipt>;
+    /** Execute one ordinary action, normally by calling `PmClient.run`. */
+    execute(action: TAction): Promise<EpisodeActionReceipt<TOutput>>;
+    /** Read immutable grading state from the workspace system of record. */
+    readRecordedState(): Promise<WorkspaceRecordedState>;
+}
+/** One deterministic entry in a portable episode trajectory. */
+export interface EpisodeTrajectoryEntry {
+    /** Monotonic event number within the isolated episode. */
+    sequence: number;
+    /** Stable event classification. */
+    kind: "reset" | "observation" | "action" | "verdict" | "close";
+    /** Snapshot, state, or observation tier associated with the event. */
+    state_id: string;
+}
+/** Closed episode evidence without reward or framework-specific shaping. */
+export interface ClosedEpisode {
+    /** Deterministic total verdict. */
+    verdict: VerdictResult;
+    /** Complete bounded trajectory. */
+    trajectory: readonly EpisodeTrajectoryEntry[];
+    /** Explicitly absent to prevent verdicts from becoming reward signals. */
+    reward?: never;
+}
+/** Isolated runtime returned for one declared agent episode. */
+export interface PmEpisodeSession<TAction, TOutput> {
+    /** Observe recorded state through the declared disclosure ladder. */
+    observe(): Promise<ObservationResult<RecordedStateObject>>;
+    /** Execute one bounded ordinary project-management action. */
+    step(action: TAction): Promise<EpisodeActionReceipt<TOutput>>;
+    /** Evaluate the current recorded state without closing the session. */
+    score(): Promise<VerdictResult>;
+    /** Evaluate and close the episode, returning immutable evidence. */
+    close(): Promise<ClosedEpisode>;
+}
+/** Validate, clone, and freeze a portable observation declaration. */
+export declare function defineObservationContract(declaration: ObservationContract): ObservationContract;
+/** Describe guaranteed and calibrated observation cost before collection. */
+export declare function describeObservationCost(contract: ObservationContract): ObservationCostDescription;
+/** Serve the richest declared tier that fits both caller and tier ceilings. */
+export declare function serveDeclaredObservation<T>(contract: ObservationContract, collect: (tier: ObservationTier) => Promise<T>, request: ObservationRequest): Promise<ObservationResult<T>>;
+/** Validate, clone, and freeze a portable total-verdict declaration. */
+export declare function defineVerdictContract(declaration: VerdictContract): VerdictContract;
+/** Evaluate a total verdict exclusively from one immutable recorded snapshot. */
+export declare function evaluateVerdictContract(contract: VerdictContract, recorded: WorkspaceRecordedState): VerdictResult;
+/** Validate, clone, and freeze a portable episode specification. */
+export declare function defineEpisodeSpecification(declaration: EpisodeSpecification): EpisodeSpecification;
+/** Open one isolated, deterministic episode around an adapter's ordinary actions. */
+export declare function openPmEpisode<TAction, TOutput = unknown>(specification: EpisodeSpecification, adapter: EpisodeRuntimeAdapter<TAction, TOutput>): Promise<PmEpisodeSession<TAction, TOutput>>;