agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/cli/commands/state/decisions.js

@@ -0,0 +1,387 @@
+/**
+ * `state decisions` query (decisions.yaml + archive) plus the
+ * decision context enrichment utilities consumed by prime.
+ *
+ * The contract for decision context: never infer satisfaction from
+ * downstream references, commits, or compacted history. Only
+ * `state == user_confirmed_satisfied` with explicit
+ * `user_confirmation` metadata is reported as user-confirmed
+ * satisfied; everything else carries a `review_needed` flag and
+ * a `caveats` array.
+ */
+import { extractEntries, } from "../../stateQuery.js";
+import { out } from "./shared.js";
+import { hydrateDecisionRecords, } from "../../../state/decisionOverlay.js";
+import { listDecisionEntities } from "../../../state/decisionEntities.js";
+import { emitStructured } from "../../structured.js";
+import YAML from "yaml";
+const DECISION_CONTEXT_FIELDS = [
+    "number",
+    "date",
+    "question",
+    "context",
+    "alternatives",
+    "choice",
+    "reasoning",
+    "confidence",
+    "feeds_into",
+    "satisfaction",
+];
+const PRIORITY_FIELDS = [
+    "number", "name", "title", "date", "timestamp", "status",
+    "phase", "choice", "grade", "type", "label", "trajectory", "confidence",
+];
+const DECISION_ARCHIVE_RE = /Decision\s+(?<number>\d+)(?:\s+\((?<date>\d{4}-\d{2}-\d{2})\))?:\s*(?<summary>.*)/;
+export function displayFields(fields, limit = 6) {
+    const ordered = PRIORITY_FIELDS.filter((p) => p in fields);
+    for (const fn of Object.keys(fields)) {
+        if (!ordered.includes(fn))
+            ordered.push(fn);
+    }
+    return ordered.slice(0, limit);
+}
+function isEmptyValue(v) {
+    // cast: v is a field value from a parsed decisions.yaml entry (IO boundary)
+    return (v === null ||
+        v === undefined ||
+        v === "" ||
+        (Array.isArray(v) && v.length === 0) ||
+        (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0));
+}
+function decisionArchiveEntry(entry) {
+    // cast: entry comes from the parsed decisions archive array (YAML IO boundary)
+    const archiveEntry = entry && typeof entry === "object" && !Array.isArray(entry) ? { ...entry } : { summary: String(entry) };
+    archiveEntry.compacted = true;
+    const summary = String(archiveEntry.summary ?? "");
+    const match = DECISION_ARCHIVE_RE.exec(summary);
+    if (match && match.groups) {
+        if (!("number" in archiveEntry))
+            archiveEntry.number = parseInt(match.groups.number, 10);
+        if (match.groups.date && !("date" in archiveEntry))
+            archiveEntry.date = match.groups.date;
+    }
+    return archiveEntry;
+}
+export function extractDecisionEntries(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return extractEntries(data);
+    // cast: data is the parsed decisions artifact from loadArtifact (YAML IO boundary)
+    const d = data;
+    const decisions = d.decisions ?? [];
+    const archive = d.archive ?? [];
+    const entries = Array.isArray(decisions)
+        ? decisions.filter((e) => Boolean(e && typeof e === "object" && !Array.isArray(e)))
+        : [];
+    if (Array.isArray(archive)) {
+        for (const entry of archive)
+            entries.push(decisionArchiveEntry(entry));
+    }
+    return entries;
+}
+export function hydrateDecisionEntries(entries, projectRoot = process.cwd()) {
+    return hydrateDecisionRecords(entries, projectRoot);
+}
+function decisionFieldMissing(entry, field) {
+    return isEmptyValue(entry[field]);
+}
+function decisionDownstreamReferences(entry) {
+    const value = entry.feeds_into;
+    if (value === null || value === undefined || value === "")
+        return null;
+    let refs;
+    if (Array.isArray(value)) {
+        refs = value.map((item) => String(item).trim()).filter((s) => s);
+    }
+    else {
+        refs = String(value)
+            .split(",")
+            .map((part) => part.trim())
+            .filter((s) => s);
+    }
+    if (refs.length === 0)
+        return null;
+    return refs.map((ref) => ({ source_field: "feeds_into", reference: ref }));
+}
+export function decisionSatisfactionContext(entry) {
+    const satisfaction = entry.satisfaction;
+    if (!satisfaction || typeof satisfaction !== "object" || Array.isArray(satisfaction)) {
+        return {
+            state: null,
+            evidence: null,
+            user_confirmation: null,
+            review_needed: true,
+            source: "missing_legacy_state",
+            caveats: ["Missing legacy satisfaction state is not treated as satisfied."],
+        };
+    }
+    // cast: satisfaction is read from a parsed decisions.yaml entry (IO boundary)
+    const sat = satisfaction;
+    const state = sat.state;
+    const evidence = sat.evidence ?? null;
+    const userConfirmation = sat.user_confirmation ?? null;
+    const explicitReviewNeeded = sat.review_needed === true;
+    let caveats = [];
+    let reviewNeeded = true;
+    let source = "decision.satisfaction";
+    if (state === null || state === undefined || state === "") {
+        source = "missing_legacy_state";
+        caveats.push("Missing legacy satisfaction state is not treated as satisfied.");
+    }
+    else if (state === "user_confirmed_satisfied") {
+        // cast: user_confirmation is read from a parsed decisions.yaml entry (IO boundary)
+        const confirmation = userConfirmation && typeof userConfirmation === "object" && !Array.isArray(userConfirmation)
+            ? userConfirmation
+            : {};
+        reviewNeeded =
+            !isNonEmptyText(confirmation.confirmed_by) || !isNonEmptyText(confirmation.confirmed_at);
+        if (reviewNeeded)
+            caveats.push("User-confirmed satisfaction is missing explicit user confirmation metadata.");
+    }
+    else if (state === "provisionally_satisfied") {
+        if (!isNonEmptyText(evidence))
+            caveats.push("Provisional satisfaction is missing concrete evidence.");
+        caveats.push("Provisional satisfaction still requires user confirmation.");
+    }
+    else if (state === "open") {
+        caveats.push("Satisfaction state is open and requires review.");
+    }
+    else {
+        caveats.push("Satisfaction state is missing or unrecognized and requires review.");
+    }
+    if (explicitReviewNeeded) {
+        reviewNeeded = true;
+        caveats.push("Decision satisfaction is explicitly marked review_needed.");
+    }
+    const originalCaveats = sat.caveats;
+    if (Array.isArray(originalCaveats))
+        caveats = [...originalCaveats.map((c) => String(c)), ...caveats];
+    else if (typeof originalCaveats === "string")
+        caveats = [originalCaveats, ...caveats];
+    const enriched = { ...sat };
+    if (!("evidence" in enriched))
+        enriched.evidence = evidence;
+    if (!("user_confirmation" in enriched))
+        enriched.user_confirmation = userConfirmation;
+    enriched.review_needed = reviewNeeded;
+    enriched.source = source;
+    enriched.caveats = caveats;
+    return enriched;
+}
+function isNonEmptyText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function decisionContextEntry(entry, options = {}) {
+    const enriched = { ...entry };
+    const inferOutcome = options.inferOutcome !== false;
+    if (inferOutcome &&
+        (enriched.outcome === null || enriched.outcome === undefined || enriched.outcome === "") &&
+        enriched.choice !== null && enriched.choice !== undefined && enriched.choice !== "") {
+        enriched.outcome = enriched.choice;
+    }
+    const compacted = Boolean(enriched.compacted) ||
+        ("summary" in enriched &&
+            ["question", "reasoning", "confidence"].some((field) => decisionFieldMissing(enriched, field)));
+    const missingFields = DECISION_CONTEXT_FIELDS.filter((field) => decisionFieldMissing(enriched, field));
+    if ((inferOutcome && decisionFieldMissing(enriched, "choice") && decisionFieldMissing(enriched, "outcome")) ||
+        (!inferOutcome && decisionFieldMissing(enriched, "outcome"))) {
+        missingFields.push("outcome");
+    }
+    const downstreamReferences = decisionDownstreamReferences(enriched);
+    const caveats = [];
+    if (compacted)
+        caveats.push("Decision entry is compacted; full decision context is not available in this CLI result.");
+    if (missingFields.length > 0)
+        caveats.push("Decision entry is missing one or more full-detail context fields.");
+    if (downstreamReferences === null) {
+        caveats.push("No explicit downstream consequence references were present; none were inferred.");
+    }
+    const satisfaction = decisionSatisfactionContext(enriched);
+    if (satisfaction.review_needed) {
+        caveats.push("Decision satisfaction requires user review; missing legacy state is not treated as satisfied.");
+    }
+    enriched.satisfaction = satisfaction;
+    enriched.downstream_consequence_references = downstreamReferences;
+    enriched.context_complete =
+        !compacted && missingFields.length === 0 && downstreamReferences !== null && !satisfaction.review_needed;
+    enriched.missing_fields = missingFields;
+    enriched.compacted = compacted;
+    enriched.caveats = caveats;
+    return enriched;
+}
+export function decisionSourceContract(source, entries, filters) {
+    const sourceExists = Boolean(source.exists);
+    const activeFilters = Object.fromEntries(Object.entries(filters).filter(([, v]) => v !== null && v !== undefined));
+    const filteredNoMatch = sourceExists && Object.keys(activeFilters).length > 0 && entries.length === 0;
+    const compactedEntries = entries.filter((e) => e.compacted).length;
+    const entriesWithMissingFields = entries.filter((e) => Array.isArray(e.missing_fields) && e.missing_fields.length > 0).length;
+    const entriesWithoutDownstream = entries.filter((e) => e.downstream_consequence_references === null).length;
+    const entriesRequiringSatisfactionReview = entries.filter((e) => e.satisfaction && typeof e.satisfaction === "object" && !Array.isArray(e.satisfaction) && e.satisfaction.review_needed).length;
+    const userConfirmedSatisfied = entries.filter((e) => e.satisfaction &&
+        typeof e.satisfaction === "object" &&
+        !Array.isArray(e.satisfaction) &&
+        e.satisfaction.state === "user_confirmed_satisfied" &&
+        !e.satisfaction.review_needed).length;
+    const completeForReturned = sourceExists && entries.every((e) => e.context_complete === true);
+    const completeForNormalDeliberation = sourceExists;
+    const caveats = [
+        "Downstream consequence references are derived only from explicit structured feeds_into values; no references are inferred.",
+        "Compacted archive decisions are not expanded by this command and are not complete full-detail decision context.",
+    ];
+    if (!sourceExists)
+        caveats.push("Decision artifact is missing or unavailable; no decision context is available from this command result.");
+    if (filteredNoMatch)
+        caveats.push("Filtered result is empty; no returned decisions match the filter, but the decision artifact was available.");
+    if (entriesWithMissingFields)
+        caveats.push("One or more returned decisions are missing full-detail context fields.");
+    if (entriesWithoutDownstream)
+        caveats.push("One or more returned decisions lack explicit downstream consequence references.");
+    if (entriesRequiringSatisfactionReview)
+        caveats.push("One or more returned decisions require satisfaction review; satisfaction is never inferred from downstream references.");
+    return {
+        artifact: "decisions",
+        canonical_artifact_label: "decisions",
+        path: source.path,
+        complete_for_returned_decisions: completeForReturned,
+        complete_for_decision_context: completeForReturned,
+        complete_for_returned_full_detail: completeForReturned,
+        complete_for_normal_deliberation_context: completeForNormalDeliberation,
+        completeness: {
+            returned_decisions: entries.length,
+            context_complete: completeForReturned,
+            returned_full_detail_complete: completeForReturned,
+            normal_deliberation_context: completeForNormalDeliberation,
+            filtered_no_match: filteredNoMatch,
+            source_exists: sourceExists,
+            compacted_entries: compactedEntries,
+            entries_with_missing_fields: entriesWithMissingFields,
+            entries_without_downstream_references: entriesWithoutDownstream,
+            entries_requiring_satisfaction_review: entriesRequiringSatisfactionReview,
+            user_confirmed_satisfied_entries: userConfirmedSatisfied,
+        },
+        included_fields: [
+            ...DECISION_CONTEXT_FIELDS,
+            "outcome",
+            "downstream_consequence_references",
+            "context_complete",
+            "missing_fields",
+            "compacted",
+            "caveats",
+        ],
+        satisfaction_context: {
+            owner: "decision entry",
+            state_field: "satisfaction.state",
+            evidence_field: "satisfaction.evidence",
+            confirmation_field: "satisfaction.user_confirmation",
+            review_needed_field: "satisfaction.review_needed",
+            confirmation_policy: "Only satisfaction.state=user_confirmed_satisfied with explicit user_confirmation metadata is reported as user-confirmed satisfied.",
+            non_inference_policy: "Do not infer satisfaction from feeds_into, commits, downstream files, generated references, or compacted history.",
+        },
+        normal_deliberation_context: {
+            use_complete_for_normal_deliberation_context: true,
+            legacy_full_detail_signal: "complete_for_decision_context",
+            guidance: "For normal deliberation, use returned entries plus missing_fields, compacted, caveats, " +
+                "and satisfaction review state. Do not use the legacy full-detail completeness flag " +
+                "as a reason to reread the raw decision artifact.",
+        },
+        decision_context_truth_table: {
+            full_detail_entries: {
+                full_detail_complete: true,
+                normal_deliberation_context_complete: true,
+                raw_artifact_read_required: false,
+            },
+            compacted_archive_entries: {
+                full_detail_complete: false,
+                normal_deliberation_context_complete: true,
+                raw_artifact_read_required: false,
+                carry_forward: ["missing_fields", "compacted", "caveats"],
+            },
+            entries_with_missing_full_detail_fields: {
+                full_detail_complete: false,
+                normal_deliberation_context_complete: true,
+                raw_artifact_read_required: false,
+                carry_forward: ["missing_fields", "caveats"],
+            },
+            satisfaction_review_needed: {
+                full_detail_complete: false,
+                normal_deliberation_context_complete: true,
+                raw_artifact_read_required: false,
+                carry_forward: ["satisfaction.review_needed", "caveats"],
+            },
+            filtered_no_match: {
+                full_detail_complete: true,
+                normal_deliberation_context_complete: true,
+                raw_artifact_read_required: false,
+                meaning: "The artifact exists, but no returned decisions matched the filter.",
+            },
+            missing_or_unavailable_artifact: {
+                full_detail_complete: false,
+                normal_deliberation_context_complete: false,
+                raw_artifact_read_required: false,
+                meaning: "No decision state is available from the CLI result; use CLI fallback or diagnostics before raw artifact repair.",
+            },
+        },
+        missing_full_detail_boundary: {
+            applies_when: "returned decisions have missing_fields or context_complete=false",
+            normal_behavior: "Use present structured fields only and preserve missing_fields/caveats downstream.",
+            raw_artifact_read_required: false,
+            do_not: "Do not infer absent reasoning, alternatives, confidence, feeds_into, outcome, or downstream references.",
+        },
+        missing_artifact_boundary: {
+            applies_when: "source.exists=false",
+            normal_behavior: "Treat decision context as unavailable from this result; do not infer historical decisions.",
+            raw_artifact_read_required: false,
+            diagnostic_boundary: "Raw artifact access is reserved for explicit artifact repair/corruption or CLI-defect investigation.",
+        },
+        filtered_result_boundary: {
+            applies_when: "filters are present and entries=[] while source.exists=true",
+            normal_behavior: "Treat the result as no matching returned decisions, not as missing decision state.",
+            raw_artifact_read_required: false,
+        },
+        satisfaction_review_boundary: {
+            applies_when: "one or more entries have satisfaction.review_needed=true",
+            normal_behavior: "Carry satisfaction review pressure forward; only user confirmation can make a decision user-confirmed satisfied.",
+            raw_artifact_read_required: false,
+            do_not: "Do not infer satisfaction from downstream references, commits, generated files, or compacted history.",
+        },
+        compacted_history_boundary: {
+            applies_when: "returned entries have compacted=true",
+            normal_behavior: "Use the compact summary and retained fields; preserve compacted/missing_fields/caveats downstream.",
+            raw_artifact_read_required: false,
+            do_not: "Do not expand archive decisions or reconstruct missing context from git history.",
+        },
+        raw_artifact_access_boundary: {
+            normal_deliberation: "skip raw decision-state reads when complete_for_normal_deliberation_context=true",
+            allowed_raw_artifact_uses: [
+                "Discuss-owned decision writes or repairs",
+                "artifact corruption diagnostics",
+                "CLI defect investigation",
+            ],
+        },
+        raw_artifact_reads_required: false,
+        raw_artifact_read_policy: "Use `agentera state decisions list --limit 20 --format json` for bounded normal deliberation discovery; " +
+            "use `agentera state decisions get --id ID --format json` for exact detail, and key normal use off " +
+            "complete_for_normal_deliberation_context. " +
+            "Do not read raw decision state unless investigating entity corruption or CLI defects; " +
+            "historical compacted gaps are exposed through missing_fields and caveats.",
+        caveats,
+        fallback_behavior: {
+            normal: "Use this command's entries and source_contract; no raw decision artifact read is required for returned full-detail or compacted decision entries.",
+            filtered_result: "The same per-decision guarantees apply after filters; an empty filtered result means no matching returned decisions.",
+            missing_or_incomplete: "If a required field is missing, treat only the present structured fields as authoritative and do not infer absent context.",
+            satisfaction: "Use only each entry's satisfaction object for satisfaction state. Missing, open, provisional, or unconfirmed satisfaction requires review and must not be reported as user-confirmed satisfied.",
+            compacted_history: "Compacted archive decisions are included with explicit missing_fields and caveats; treat absent historical context as unavailable during normal deliberation.",
+        },
+        fallback_policy: "If the decision artifact is missing or CLI state appears defective, use CLI fallback/diagnostic paths before raw artifact repair; do not raw-read merely because returned decisions are compacted or incomplete.",
+        filters: activeFilters,
+    };
+}
+export function queryDecisions(args, _schemas, io) {
+    const output = out(io);
+    const format = args.format ?? "text";
+    const response = listDecisionEntities(process.cwd(), args.limit ?? undefined, args.topic ?? undefined, args.cursor ?? undefined, { format });
+    if (format === "text")
+        output(YAML.stringify(response));
+    else
+        emitStructured(response, format, output);
+    return 0;
+}

package/dist/cli/commands/state/docs.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import YAML from "yaml";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { listTodoDocsEntities } from "../../../state/todoDocsEntities.js";
+import { artifactPath, discoverSchemasDir } from "../../appContext.js";
+import { registryArtifactPath } from "../../orientation.js";
+import { capabilityStartupComplete } from "../../startupCompletenessContract.js";
+import { asList, loadArtifact } from "../../stateQuery.js";
+import { emitStructured } from "../../structured.js";
+import { err, out } from "./shared.js";
+export function queryDocs(args, schemas, io) {
+    const output = out(io);
+    const format = args.format ?? "text";
+    const profilePath = registryArtifactPath("profile", discoverSchemasDir());
+    const profileStatus = fs.existsSync(profilePath) ? "loaded" : "not found";
+    const info = schemas.docs;
+    if (!info)
+        throw new Error("docs schema is unavailable");
+    const singletonPath = artifactPath(info, "docs");
+    const data = loadArtifact(singletonPath);
+    try {
+        const singleton = data !== null && typeof data === "object" && !Array.isArray(data)
+            ? data
+            : {};
+        const mapping = asList(singleton.mapping);
+        const coverage = singleton.coverage && typeof singleton.coverage === "object" && !Array.isArray(singleton.coverage)
+            ? singleton.coverage
+            : {};
+        const conventions = singleton.conventions && typeof singleton.conventions === "object" && !Array.isArray(singleton.conventions)
+            ? singleton.conventions
+            : {};
+        const summary = {
+            last_audit: singleton.last_audit,
+            conventions,
+            mapping,
+            mapping_entries: mapping.length,
+            coverage,
+            source_contract: {
+                capability_startup_complete: capabilityStartupComplete({ profileStatus }),
+                raw_artifact_reads_required: false,
+                inventory_authority: "canonical_entity_files",
+                singleton_authority: singletonPath,
+            },
+        };
+        const reservedUtf8Bytes = Math.max(Buffer.byteLength(JSON.stringify({ summary }, null, 2)), Buffer.byteLength(YAML.stringify({ summary }))) + 256;
+        const response = listTodoDocsEntities(process.cwd(), "docs", args.limit ?? undefined, undefined, {
+            ...(args.topic ? { topic: args.topic } : {}),
+            ...(args.status ? { status: args.status } : {}),
+        }, { format, reservedUtf8Bytes });
+        const projected = { ...response, summary };
+        if (format === "json" || format === "yaml")
+            emitStructured(projected, format, output);
+        else {
+            output(`Docs: last_audit=${singleton.last_audit ?? "-"}\nMapping: entries=${mapping.length}\n`);
+            for (const entry of response.entries) {
+                output(`${entry.id} document=${entry.record.document} | path=${entry.record.path} | last_updated=${entry.record.last_updated} | status=${entry.record.status}\n`);
+            }
+        }
+        return 0;
+    }
+    catch (error) {
+        if (!(error instanceof StateRetrievalFailure))
+            throw error;
+        if (format === "json" || format === "yaml")
+            emitStructured(error.body, format, output);
+        else
+            err(io)(YAML.stringify(error.body));
+        return error.exitCode;
+    }
+}

package/dist/cli/commands/state/experimentRecords.js

@@ -0,0 +1,151 @@
+import YAML from "yaml";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { getExperimentEntity, listExperimentEntities } from "../../../state/objectiveExperimentEntities.js";
+import { emitStructured } from "../../structured.js";
+import { entityListFamily, entityListValidValues } from "../../../state/entityRetrievalHelp.js";
+function requestedFormat(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        const value = token === "--format" ? argv[index + 1] : token.startsWith("--format=") ? token.slice(9) : undefined;
+        if (value === "json" || value === "yaml")
+            return value;
+    }
+    return "text";
+}
+function failure(message, verb) {
+    const list = verb === "list";
+    const family = entityListFamily("experiments");
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "invalid_request",
+            message,
+            syntax: list
+                ? family.syntax
+                : family.get,
+            example: list
+                ? family.example
+                : "agentera state experiments get --id qjtrmnpvka --format json",
+            recovery: list ? `Run \`${family.example}\`; no state was changed.` : "Use bare ten-letter entity IDs and retry; no state was changed.",
+            valid_values: list
+                ? entityListValidValues(family)
+                : ["get", "--id ID", "--format text|json|yaml"],
+        },
+    }, 2);
+}
+function value(argv, index, name) {
+    const token = argv[index];
+    if (token.startsWith(`${name}=`))
+        return { value: token.slice(name.length + 1), next: index + 1 };
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return { value: next, next: index + 2 };
+}
+function parse(argv, verb) {
+    const family = entityListFamily("experiments");
+    let format = "text";
+    let objective;
+    let id;
+    let limit = family.bounds.default;
+    let cursor;
+    const selector = {};
+    const seen = new Set();
+    for (let index = 0; index < argv.length;) {
+        const token = argv[index];
+        if (verb === "list" && token === "--ids-only") {
+            if (selector.idsOnly)
+                throw failure("--ids-only may only be supplied once", verb);
+            selector.idsOnly = true;
+            index += 1;
+            continue;
+        }
+        const allowed = verb === "list" ? ["--format", "--objective", "--limit", "--cursor", "--fields"] : ["--format", "--id"];
+        const name = allowed.find((flag) => token === flag || token.startsWith(`${flag}=`));
+        if (!name)
+            throw failure(`unrecognized argument '${token}'`, verb);
+        if (seen.has(name))
+            throw failure(`${name} may only be supplied once`, verb);
+        seen.add(name);
+        let parsed;
+        try {
+            parsed = value(argv, index, name);
+        }
+        catch (error) {
+            throw failure(error.message, verb);
+        }
+        index = parsed.next;
+        if (name === "--format") {
+            if (!family.formats.includes(parsed.value))
+                throw failure(`invalid --format '${parsed.value}'`, verb);
+            format = parsed.value;
+        }
+        else if (name === "--objective")
+            objective = parsed.value;
+        else if (name === "--id")
+            id = parsed.value;
+        else if (name === "--cursor")
+            cursor = parsed.value;
+        else if (name === "--fields")
+            selector.fields = parsed.value;
+        else {
+            if (!/^[1-9][0-9]*$/.test(parsed.value) || Number(parsed.value) < family.bounds.minimum || Number(parsed.value) > family.bounds.maximum)
+                throw failure(`--limit must be an integer from ${family.bounds.minimum} through ${family.bounds.maximum}`, verb);
+            limit = Number(parsed.value);
+        }
+    }
+    if (verb === "list" && !objective)
+        throw failure("--objective is required", verb);
+    if (verb === "get" && !id)
+        throw failure("--id is required", verb);
+    return { format, objective, id, limit, cursor, selector };
+}
+function emitFailure(error, format, io) {
+    if (format === "json" || format === "yaml")
+        emitStructured(error.body, format, io.out ?? ((text) => process.stdout.write(text)));
+    else {
+        const detail = error.body.error;
+        (io.err ?? ((text) => process.stderr.write(text)))([
+            `Error: ${detail.message}`,
+            `Class: ${detail.class}`,
+            `Valid forms: ${(detail.valid_values ?? [detail.syntax]).join("; ")}`,
+            `Example: ${detail.example}`,
+            `Recovery: ${detail.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return error.exitCode;
+}
+export function runExperimentRecords(argv, io) {
+    const format = requestedFormat(argv);
+    const verb = argv[0];
+    if (verb !== "list" && verb !== "get")
+        return emitFailure(failure(`expected 'list' or 'get', received '${verb ?? "nothing"}'`, "list"), format, io);
+    try {
+        const args = parse(argv.slice(1), verb);
+        const response = verb === "list"
+            ? listExperimentEntities(process.cwd(), args.objective, args.limit, args.cursor, { format: args.format, selector: args.selector })
+            : getExperimentEntity(process.cwd(), args.id);
+        const output = io.out ?? ((text) => process.stdout.write(text));
+        if (args.format === "json" || args.format === "yaml")
+            emitStructured(response, args.format, output);
+        else
+            output(YAML.stringify(response));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof StateRetrievalFailure)
+            return emitFailure(error, format, io);
+        return emitFailure(new StateRetrievalFailure({
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: {
+                class: "unsupported_state",
+                message: error.message,
+                syntax: "agentera state experiments list --objective ID [options] | agentera state experiments get --id ID [--format text|json|yaml]",
+                example: "agentera state experiments list --objective qjtrmnpvka --format json",
+                recovery: "Use supported objective-scoped experiment state and retry; no state was changed.",
+            },
+        }, 1), format, io);
+    }
+}

package/dist/cli/commands/state/experiments.js

@@ -0,0 +1,14 @@
+import { emitStructured } from "../../structured.js";
+import { listCurrentExperimentEntities } from "../../../state/objectiveExperimentEntities.js";
+import YAML from "yaml";
+import { out } from "./shared.js";
+export function queryExperiments(args, _schemas, io) {
+    const format = args.format ?? "text";
+    const response = listCurrentExperimentEntities(process.cwd(), args.objective ?? undefined, args.limit ?? undefined, args.cursor ?? undefined, { topic: args.topic ?? undefined, status: args.status ?? undefined }, { format });
+    const output = out(io);
+    if (format === "text")
+        output(YAML.stringify(response));
+    else
+        emitStructured(response, format, output);
+    return 0;
+}