@unbrained/pm-cli 2026.9.2 → 2026.9.4

package/dist/sdk/environment/agent-environment.js

@@ -0,0 +1,467 @@
+/**
+ * @module sdk/agent-environment
+ *
+ * Declares reproducible, budgeted agent observations, total verdicts, and
+ * isolated project-management episodes over adapter-provided recorded state.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="38cb0b88-262f-5061-b95a-f4532bc52613")}catch(e){}}();
+import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
+import { runWithAgentSessionContext } from "../agent-session-context.js";
+import { defineWorkspaceRecipe, } from "../workspace-recipe.js";
+/** Schema identifier for a portable observation contract. */
+export const PM_OBSERVATION_SCHEMA = "pm.agent-observation/v1";
+/** Schema identifier for a deterministic verdict contract. */
+export const PM_VERDICT_SCHEMA = "pm.agent-verdict/v1";
+/** Schema identifier for a bounded agent-environment episode. */
+export const PM_EPISODE_SCHEMA = "pm.agent-episode/v1";
+function assertPositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive safe integer.`);
+    }
+}
+/** Reject blank user-facing identifiers at the declaration boundary. */
+function assertNonEmpty(value, label) {
+    if (value.trim().length === 0)
+        throw new Error(`${label} must not be empty.`);
+}
+/** Recursively freeze a structured clone without mutating caller input. */
+function frozenCopy(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const nested of Object.values(value))
+            frozenCopy(nested);
+    }
+    return value;
+}
+/** Validate bounded read declarations and reject arithmetic overflow. */
+function validateObservationReads(reads) {
+    if (reads.length === 0) {
+        throw new Error("observation.reads must declare at least one bounded read.");
+    }
+    let readCeiling = 0;
+    for (const read of reads) {
+        assertNonEmpty(read.command, "observation.reads.command");
+        assertPositiveInteger(read.budget_tokens, "observation.reads.budget_tokens");
+        readCeiling += read.budget_tokens;
+        if (!Number.isSafeInteger(readCeiling)) {
+            throw new Error("observation read ceilings exceed safe integer range.");
+        }
+    }
+}
+/** Validate that emitted-byte expectations are supported by bounded samples. */
+function validateObservationCalibration(calibration) {
+    if (calibration.basis !== "emitted_bytes") {
+        throw new Error("observation calibration must use emitted_bytes.");
+    }
+    for (const sample of calibration.samples) {
+        if (!Number.isSafeInteger(sample) || sample < 0) {
+            throw new Error("observation calibration samples must be non-negative safe integers.");
+        }
+    }
+    if (calibration.samples.length === 0) {
+        throw new Error("observation calibration must include at least one sample.");
+    }
+    assertPositiveInteger(calibration.expected_emitted_bytes, "observation.calibration.expected_emitted_bytes");
+    if (!Number.isSafeInteger(calibration.tolerance_bytes) ||
+        calibration.tolerance_bytes < 0) {
+        throw new Error("observation.calibration.tolerance_bytes must be a non-negative safe integer.");
+    }
+    const sampleMean = calibration.samples.reduce((total, sample) => total + sample, 0) /
+        calibration.samples.length;
+    if (Math.abs(sampleMean - calibration.expected_emitted_bytes) >
+        calibration.tolerance_bytes) {
+        throw new Error("observation expected_emitted_bytes is outside the calibrated sample tolerance.");
+    }
+}
+/** Validate the ordered disclosure ladder and every projected field path. */
+function validateObservationTiers(tiers) {
+    if (tiers.length === 0) {
+        throw new Error("observation.tiers must declare a degradation ladder.");
+    }
+    const tierIds = new Set();
+    let previousTierBudget = Number.POSITIVE_INFINITY;
+    for (const tier of tiers) {
+        assertNonEmpty(tier.id, "observation.tiers.id");
+        assertPositiveInteger(tier.max_tokens, "observation.tiers.max_tokens");
+        if (tierIds.has(tier.id))
+            throw new Error(`Duplicate observation tier: ${tier.id}.`);
+        tierIds.add(tier.id);
+        if (tier.max_tokens > previousTierBudget) {
+            throw new Error("observation tiers must be ordered from largest to smallest max_tokens.");
+        }
+        previousTierBudget = tier.max_tokens;
+        const fields = new Set();
+        for (const field of tier.fields) {
+            parseFieldPath(field, "observation.tiers.fields");
+            if (fields.has(field)) {
+                throw new Error(`Duplicate observation tier field: ${field}.`);
+            }
+            fields.add(field);
+        }
+    }
+}
+/** Validate, clone, and freeze a portable observation declaration. */
+export function defineObservationContract(declaration) {
+    if (declaration.schema !== PM_OBSERVATION_SCHEMA) {
+        throw new Error(`observation.schema must be ${PM_OBSERVATION_SCHEMA}.`);
+    }
+    assertNonEmpty(declaration.id, "observation.id");
+    assertPositiveInteger(declaration.version, "observation.version");
+    validateObservationReads(declaration.reads);
+    validateObservationCalibration(declaration.calibration);
+    if (declaration.corpus_dependence.kind === "bounded") {
+        assertNonEmpty(declaration.corpus_dependence.dimension, "observation.corpus_dependence.dimension");
+        assertPositiveInteger(declaration.corpus_dependence.maximum, "observation.corpus_dependence.maximum");
+    }
+    validateObservationTiers(declaration.tiers);
+    return frozenCopy(structuredClone(declaration));
+}
+/** Describe guaranteed and calibrated observation cost before collection. */
+export function describeObservationCost(contract) {
+    return {
+        contract_id: contract.id,
+        contract_version: contract.version,
+        guaranteed_ceiling_tokens: contract.reads.reduce((total, read) => total + read.budget_tokens, 0),
+        expected_emitted_bytes: contract.calibration.expected_emitted_bytes,
+        expected_tokens: Math.ceil(contract.calibration.expected_emitted_bytes / 4),
+        tolerance_bytes: contract.calibration.tolerance_bytes,
+        calibration_basis: "emitted_bytes",
+        corpus_dependence: contract.corpus_dependence,
+    };
+}
+/** Serve the richest declared tier that fits both caller and tier ceilings. */
+export async function serveDeclaredObservation(contract, collect, request) {
+    assertPositiveInteger(request.budget_tokens, "observation request budget_tokens");
+    const attempted = [];
+    for (const [index, tier] of contract.tiers.entries()) {
+        attempted.push(tier.id);
+        const payload = await collect(tier);
+        const emittedBytes = Buffer.byteLength(stableStringify(payload), "utf8");
+        const estimatedTokens = Math.ceil(emittedBytes / 4);
+        if (estimatedTokens <= Math.min(request.budget_tokens, tier.max_tokens)) {
+            return {
+                status: "served",
+                payload,
+                receipt: {
+                    contract_id: contract.id,
+                    contract_version: contract.version,
+                    served_tier: tier.id,
+                    degraded: index > 0,
+                    attempted_tiers: attempted,
+                    emitted_bytes: emittedBytes,
+                    estimated_tokens: estimatedTokens,
+                    calibration_basis: "emitted_bytes",
+                },
+            };
+        }
+    }
+    return {
+        status: "refused",
+        reason: "no_declared_tier_fits_budget",
+        receipt: {
+            contract_id: contract.id,
+            contract_version: contract.version,
+            served_tier: null,
+            degraded: contract.tiers.length > 1,
+            attempted_tiers: attempted,
+            emitted_bytes: null,
+            estimated_tokens: null,
+            calibration_basis: "emitted_bytes",
+        },
+    };
+}
+/** Parse a safe dot path and reject prototype-mutating or ambiguous segments. */
+function parseFieldPath(path, label) {
+    const segments = path.split(".");
+    if (segments.some((segment) => segment.length === 0 ||
+        segment === "__proto__" ||
+        segment === "prototype" ||
+        segment === "constructor")) {
+        throw new Error(`${label} must be a safe, non-empty dot-separated path.`);
+    }
+    return segments;
+}
+/** Read a declared field without interpreting inherited properties. */
+function valueAtPath(root, path) {
+    let value = root;
+    for (const segment of parseFieldPath(path, "recorded field path")) {
+        if (value === null ||
+            typeof value !== "object" ||
+            !Object.hasOwn(value, segment)) {
+            return undefined;
+        }
+        value = value[segment];
+    }
+    return value;
+}
+/** Convert a safe dot path into an RFC 6901 evidence pointer. */
+function jsonPointer(path) {
+    return `/${parseFieldPath(path, "verdict predicate path")
+        .map((segment) => segment.replaceAll("~", "~0").replaceAll("/", "~1"))
+        .join("/")}`;
+}
+/** Reject equality operands that cannot survive portable JSON storage. */
+function assertPortableExpectedValue(predicate) {
+    if (predicate.kind !== "field_equals")
+        return;
+    let serializedExpected;
+    try {
+        serializedExpected = JSON.stringify(predicate.expected);
+    }
+    catch {
+        throw new Error(`Expected value for verdict predicate ${predicate.id} must be JSON serializable.`);
+    }
+    if (serializedExpected === undefined) {
+        throw new Error(`Expected value for verdict predicate ${predicate.id} must be JSON serializable.`);
+    }
+}
+/** Validate, clone, and freeze a portable total-verdict declaration. */
+export function defineVerdictContract(declaration) {
+    if (declaration.schema !== PM_VERDICT_SCHEMA) {
+        throw new Error(`verdict.schema must be ${PM_VERDICT_SCHEMA}.`);
+    }
+    assertNonEmpty(declaration.id, "verdict.id");
+    assertPositiveInteger(declaration.version, "verdict.version");
+    const predicateIds = new Set();
+    for (const predicate of declaration.predicates) {
+        assertNonEmpty(predicate.id, "verdict.predicates.id");
+        parseFieldPath(predicate.path, "verdict.predicates.path");
+        const runtimeKind = predicate.kind;
+        if (runtimeKind !== "field_equals" &&
+            runtimeKind !== "field_present" &&
+            runtimeKind !== "field_absent") {
+            throw new Error(`Unsupported verdict predicate kind for ${predicate.id}.`);
+        }
+        if (predicateIds.has(predicate.id))
+            throw new Error(`Duplicate verdict predicate: ${predicate.id}.`);
+        assertPortableExpectedValue(predicate);
+        predicateIds.add(predicate.id);
+    }
+    if (declaration.composition.operator !== "all" &&
+        declaration.composition.operator !== "any") {
+        throw new Error("verdict composition operator must be all or any.");
+    }
+    if (declaration.composition.predicate_ids.length !==
+        declaration.predicates.length) {
+        throw new Error("verdict composition must reference every predicate exactly once.");
+    }
+    const compositionIds = new Set(declaration.composition.predicate_ids);
+    if (compositionIds.size !== declaration.composition.predicate_ids.length ||
+        [...compositionIds].some((id) => !predicateIds.has(id))) {
+        throw new Error("verdict composition contains duplicate or unknown predicate ids.");
+    }
+    return frozenCopy(structuredClone(declaration));
+}
+/** Evaluate a total verdict exclusively from one immutable recorded snapshot. */
+export function evaluateVerdictContract(contract, recorded) {
+    if (contract.predicates.length === 0) {
+        return {
+            contract_id: contract.id,
+            contract_version: contract.version,
+            snapshot_id: recorded.snapshot_id,
+            outcome: "not_applicable",
+            score: null,
+            policy: "verdict_only_no_reward",
+            reason: "no_predicates_declared",
+            predicates: [],
+        };
+    }
+    const byId = new Map(contract.predicates.map((predicate) => [predicate.id, predicate]));
+    const predicates = contract.composition.predicate_ids.map((id) => {
+        const predicate = byId.get(id);
+        const observed = valueAtPath(recorded.state, predicate.path);
+        const satisfied = predicate.kind === "field_present"
+            ? observed !== undefined
+            : predicate.kind === "field_absent"
+                ? observed === undefined
+                : stableStringify(observed) === stableStringify(predicate.expected);
+        return {
+            id,
+            outcome: satisfied ? "satisfied" : "violated",
+            evidence_pointer: `${recorded.snapshot_id}#${jsonPointer(predicate.path)}`,
+            evidence_digest: sha256Hex(stableStringify(observed)),
+        };
+    });
+    const satisfiedCount = predicates.filter((predicate) => predicate.outcome === "satisfied").length;
+    const satisfied = contract.composition.operator === "all"
+        ? satisfiedCount === predicates.length
+        : satisfiedCount > 0;
+    return {
+        contract_id: contract.id,
+        contract_version: contract.version,
+        snapshot_id: recorded.snapshot_id,
+        outcome: satisfied ? "satisfied" : "violated",
+        score: satisfiedCount / predicates.length,
+        policy: "verdict_only_no_reward",
+        predicates,
+    };
+}
+/** Validate, clone, and freeze a portable episode specification. */
+export function defineEpisodeSpecification(declaration) {
+    if (declaration.schema !== PM_EPISODE_SCHEMA) {
+        throw new Error(`episode.schema must be ${PM_EPISODE_SCHEMA}.`);
+    }
+    assertNonEmpty(declaration.id, "episode.id");
+    assertPositiveInteger(declaration.version, "episode.version");
+    if (!["benchmark", "evaluation", "training", "scale_transfer"].includes(declaration.mode)) {
+        throw new Error("episode.mode is not supported.");
+    }
+    if (declaration.task_item_ids.length === 0) {
+        throw new Error("episode.task_item_ids must declare at least one pm item.");
+    }
+    for (const itemId of declaration.task_item_ids) {
+        assertNonEmpty(itemId, "episode.task_item_ids");
+    }
+    assertPositiveInteger(declaration.limits.max_actions, "episode.limits.max_actions");
+    assertPositiveInteger(declaration.limits.max_observations, "episode.limits.max_observations");
+    assertPositiveInteger(declaration.limits.max_tokens_per_observation, "episode.limits.max_tokens_per_observation");
+    for (const field of declaration.observable_fields) {
+        parseFieldPath(field, "episode.observable_fields");
+    }
+    for (const field of declaration.withheld_fields) {
+        parseFieldPath(field, "episode.withheld_fields");
+    }
+    for (const observable of declaration.observable_fields) {
+        const overlap = declaration.withheld_fields.find((withheld) => observable === withheld ||
+            observable.startsWith(`${withheld}.`) ||
+            withheld.startsWith(`${observable}.`));
+        if (overlap !== undefined) {
+            throw new Error(`Observable field ${observable} overlaps withheld field ${overlap}.`);
+        }
+    }
+    for (const tier of declaration.observation.tiers) {
+        for (const field of tier.fields) {
+            if (!declaration.observable_fields.includes(field)) {
+                throw new Error(`Observation tier field ${field} is not declared observable.`);
+            }
+        }
+    }
+    defineObservationContract(declaration.observation);
+    defineVerdictContract(declaration.verdict);
+    defineWorkspaceRecipe(declaration.recipe);
+    return frozenCopy(structuredClone(declaration));
+}
+/** Copy one selected field into a null-prototype-safe projected object. */
+function assignProjectedPath(target, path, value) {
+    const segments = parseFieldPath(path, "observation projection field");
+    let cursor = target;
+    for (const [index, segment] of segments.entries()) {
+        if (index === segments.length - 1) {
+            if (value !== undefined)
+                cursor[segment] = structuredClone(value);
+            return;
+        }
+        const nested = cursor[segment];
+        if (nested === null ||
+            typeof nested !== "object" ||
+            Array.isArray(nested)) {
+            cursor[segment] = {};
+        }
+        cursor = cursor[segment];
+    }
+}
+/** Project only declared tier fields from recorded workspace state. */
+function projectedState(state, fields) {
+    const result = {};
+    for (const field of fields)
+        assignProjectedPath(result, field, valueAtPath(state, field));
+    return result;
+}
+/** Open one isolated, deterministic episode around an adapter's ordinary actions. */
+export async function openPmEpisode(specification, adapter) {
+    const trajectory = [];
+    let actions = 0;
+    let observations = 0;
+    let closed = false;
+    let closing;
+    const context = {
+        episode: {
+            id: specification.id,
+            label: `pm agent environment v${specification.version}`,
+        },
+        provenance: { role: specification.mode, topic: "agent-environment" },
+    };
+    const reset = await runWithAgentSessionContext(context, () => adapter.reset(specification.recipe));
+    trajectory.push({ sequence: 1, kind: "reset", state_id: reset.state_id });
+    const readObservation = async () => {
+        if (closed)
+            throw new Error("episode is already closed.");
+        if (observations >= specification.limits.max_observations) {
+            throw new Error("episode exceeded limits.max_observations.");
+        }
+        observations += 1;
+        const recorded = await adapter.readRecordedState();
+        const result = await serveDeclaredObservation(specification.observation, async (tier) => projectedState(recorded.state, tier.fields), { budget_tokens: specification.limits.max_tokens_per_observation });
+        trajectory.push({
+            sequence: trajectory.length + 1,
+            kind: "observation",
+            state_id: result.receipt.served_tier ?? recorded.snapshot_id,
+        });
+        return result;
+    };
+    const evaluate = async (reservedForClose = false) => {
+        if (closed && !reservedForClose)
+            throw new Error("episode is already closed.");
+        if (observations >= specification.limits.max_observations) {
+            throw new Error("episode exceeded limits.max_observations.");
+        }
+        observations += 1;
+        const recorded = await adapter.readRecordedState();
+        const result = evaluateVerdictContract(specification.verdict, recorded);
+        trajectory.push({
+            sequence: trajectory.length + 1,
+            kind: "verdict",
+            state_id: recorded.snapshot_id,
+        });
+        return result;
+    };
+    return {
+        observe: () => runWithAgentSessionContext(context, readObservation),
+        step: async (action) => {
+            if (closed)
+                throw new Error("episode is already closed.");
+            if (actions >= specification.limits.max_actions) {
+                throw new Error("episode exceeded limits.max_actions.");
+            }
+            actions += 1;
+            const result = await runWithAgentSessionContext(context, () => adapter.execute(action));
+            trajectory.push({
+                sequence: trajectory.length + 1,
+                kind: "action",
+                state_id: result.state_id,
+            });
+            return result;
+        },
+        score: () => runWithAgentSessionContext(context, evaluate),
+        close: () => {
+            if (closing !== undefined)
+                return closing;
+            if (closed)
+                return Promise.reject(new Error("episode is already closed."));
+            closed = true;
+            const operation = runWithAgentSessionContext(context, () => evaluate(true))
+                .then((verdict) => {
+                trajectory.push({
+                    sequence: trajectory.length + 1,
+                    kind: "close",
+                    state_id: verdict.snapshot_id,
+                });
+                return {
+                    verdict,
+                    trajectory: frozenCopy(structuredClone(trajectory)),
+                };
+            })
+                .catch((error) => {
+                closed = false;
+                throw error;
+            });
+            closing = operation.finally(() => {
+                closing = undefined;
+            });
+            return closing;
+        },
+    };
+}
+//# sourceMappingURL=agent-environment.js.map
+//# debugId=38cb0b88-262f-5061-b95a-f4532bc52613

package/dist/sdk/environment/project-runtime-compatibility.d.ts

@@ -1,11 +1,19 @@
 import { PmCliError } from "../../core/shared/errors.js";
 export { PmCliError };
+/** First pm release whose history writer and reader support item-hash epoch 3. */
+export declare const HISTORY_ITEM_HASH_VERSION_3_INTRODUCED_IN = "2026.8.31";
 /** One discovered project pin that can prove the active executable is stale. */
 export interface ProjectRuntimeVersionPin {
-    /** Exact or minimum date-version extracted from the project declaration. */
+    /** Representative date-version extracted from the project declaration. */
     version: string;
     /** Redaction-safe origin of the pin. */
     source: "package.json" | "installed-package" | "package-lock.json" | "pnpm-lock.yaml" | "yarn.lock";
+    /** Whether the declaration selects one runtime, a minimum, or a bounded range. */
+    constraint: "exact" | "minimum" | "range";
+    /** Original package declaration when it conveys more than the representative version. */
+    declaration?: string;
+    /** Whether the declaration permits a reader that understands history item-hash epoch 3. */
+    history_epoch_compatible?: boolean;
 }
 /** Structured result returned by the read-only compatibility probe. */
 export interface ProjectRuntimeCompatibilityResult {
@@ -23,6 +31,14 @@ export interface ProjectRuntimeCompatibilityResult {
     mutating: boolean;
     /** Whether the active executable is older than the strongest project pin. */
     stale?: boolean;
+    /** Whether this mutation would write a history epoch a project pin cannot read. */
+    history_epoch_incompatible?: boolean;
+    /** Item-hash epoch the executing runtime writes. */
+    writer_item_hash_version?: 2 | 3;
+    /** Project runtime declaration that cannot read the writer epoch. */
+    incompatible_project_version?: string;
+    /** Origin of the incompatible project runtime declaration. */
+    incompatible_source?: ProjectRuntimeVersionPin["source"];
     /** Non-blocking diagnostic attached to stale read-only invocations. */
     warning?: ProjectRuntimeCompatibilityWarning;
     /** Whether the explicit one-invocation recovery override was accepted. */
@@ -45,6 +61,8 @@ export interface ProjectRuntimeCompatibilityWarning {
 }
 /** Compare pm date versions without accepting arbitrary semver-like prose. */
 export declare function comparePmDateVersions(left: string, right: string): number | null;
+/** Resolve the item-hash epoch written by a known pm runtime release. */
+export declare function historyItemHashVersionForRuntime(version: string): 2 | 3;
 /** Discover declared, installed, and lock-resolved versions without network I/O. */
 export declare function discoverProjectRuntimeVersionPins(projectRoot: string): ProjectRuntimeVersionPin[];
 /** Classify mutation-capable invocations while preserving explicit read modes. */