agentera 3.0.0-dev.7 → 3.0.0-dev.72

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

@@ -9,9 +9,12 @@
  * satisfied; everything else carries a `review_needed` flag and
  * a `caveats` array.
  */
-import { emitStateStructured, extractEntries, loadArtifact, missingSchemaError, sourceMetadata, stringFieldNames, structuredState, } from "../../stateQuery.js";
-import { artifactPath } from "../../appContext.js";
-import { out, err } from "./shared.js";
+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",
@@ -75,10 +78,8 @@ export function extractDecisionEntries(data) {
     }
     return entries;
 }
-function filterDecisionsByTopic(entries, topic, fields) {
-    const t = topic.toLowerCase();
-    const fnames = [...stringFieldNames(fields), "summary", "outcome"];
-    return entries.filter((entry) => fnames.some((f) => String(entry[f] ?? "").toLowerCase().includes(t)));
+export function hydrateDecisionEntries(entries, projectRoot = process.cwd()) {
+    return hydrateDecisionRecords(entries, projectRoot);
 }
 function decisionFieldMissing(entry, field) {
     return isEmptyValue(entry[field]);
@@ -121,16 +122,23 @@ export function decisionSatisfactionContext(entry) {
     const explicitReviewNeeded = sat.review_needed === true;
     let caveats = [];
     let reviewNeeded = true;
-    if (state === "user_confirmed_satisfied") {
+    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 =
-            !(userConfirmation && typeof userConfirmation === "object" && !Array.isArray(userConfirmation)) ||
-                Object.keys(userConfirmation).length === 0;
+            !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 (isEmptyValue(evidence))
+        if (!isNonEmptyText(evidence))
             caveats.push("Provisional satisfaction is missing concrete evidence.");
         caveats.push("Provisional satisfaction still requires user confirmation.");
     }
@@ -155,13 +163,18 @@ export function decisionSatisfactionContext(entry) {
     if (!("user_confirmation" in enriched))
         enriched.user_confirmation = userConfirmation;
     enriched.review_needed = reviewNeeded;
-    enriched.source = "decision.satisfaction";
+    enriched.source = source;
     enriched.caveats = caveats;
     return enriched;
 }
-export function decisionContextEntry(entry) {
+function isNonEmptyText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function decisionContextEntry(entry, options = {}) {
     const enriched = { ...entry };
-    if ((enriched.outcome === null || enriched.outcome === undefined || enriched.outcome === "") &&
+    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;
     }
@@ -169,7 +182,8 @@ export function decisionContextEntry(entry) {
         ("summary" in enriched &&
             ["question", "reasoning", "confidence"].some((field) => decisionFieldMissing(enriched, field)));
     const missingFields = DECISION_CONTEXT_FIELDS.filter((field) => decisionFieldMissing(enriched, field));
-    if (decisionFieldMissing(enriched, "choice") && decisionFieldMissing(enriched, "outcome")) {
+    if ((inferOutcome && decisionFieldMissing(enriched, "choice") && decisionFieldMissing(enriched, "outcome")) ||
+        (!inferOutcome && decisionFieldMissing(enriched, "outcome"))) {
         missingFields.push("outcome");
     }
     const downstreamReferences = decisionDownstreamReferences(enriched);
@@ -336,7 +350,7 @@ export function decisionSourceContract(source, entries, filters) {
             do_not: "Do not expand archive decisions or reconstruct missing context from git history.",
         },
         raw_artifact_access_boundary: {
-            normal_deliberation: "skip raw `.agentera/decisions.yaml` reads when complete_for_normal_deliberation_context=true",
+            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",
@@ -344,9 +358,10 @@ export function decisionSourceContract(source, entries, filters) {
             ],
         },
         raw_artifact_reads_required: false,
-        raw_artifact_read_policy: "Use `agentera decisions --format json` for normal deliberation context and key normal use off " +
+        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 `.agentera/decisions.yaml` unless investigating artifact corruption or CLI defects; " +
+            "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: {
@@ -360,44 +375,13 @@ export function decisionSourceContract(source, entries, filters) {
         filters: activeFilters,
     };
 }
-export function queryDecisions(args, schemas, io) {
-    const o = out(io);
-    const e = err(io);
-    const info = schemas.decisions;
-    if (!info) {
-        e(missingSchemaError("decisions") + "\n");
-        return 1;
-    }
-    const p = artifactPath(info, "decisions");
-    const data = loadArtifact(p);
-    let entries = extractDecisionEntries(data);
-    const topic = args.topic ?? null;
-    if (topic)
-        entries = filterDecisionsByTopic(entries, topic, info.fields);
+export function queryDecisions(args, _schemas, io) {
+    const output = out(io);
     const format = args.format ?? "text";
-    if (format !== "text") {
-        const enriched = entries.map((entry) => decisionContextEntry(entry));
-        const source = sourceMetadata("decisions", p);
-        const filters = { topic };
-        return emitStateStructured("decisions", structuredState("decisions", enriched, source, {
-            filters,
-            sourceContract: decisionSourceContract(source, enriched, filters),
-        }), format, args.fields, o, e);
-    }
-    if (entries.length === 0)
-        return 0;
-    const disp = displayFields(info.fields);
-    for (const entry of entries) {
-        const parts = [];
-        for (const fn of disp) {
-            const v = entry[fn];
-            if (v !== null && v !== undefined && v !== "" && !Array.isArray(v) && typeof v !== "object") {
-                parts.push(`${fn}=${v}`);
-            }
-        }
-        if (parts.length > 0)
-            o(parts.join(" | ") + "\n");
-    }
+    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;
 }
-//# sourceMappingURL=decisions.js.map

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

@@ -1,97 +1,70 @@
-/**
- * `state docs` query (DOCS.md / docs.yaml).
- *
- * Returns the docs index (document, path, last_updated, status) and
- * a source_contract that asserts
- * `capability_startup_complete` so prime can skip raw
- * `.agentera/docs.yaml` reads.
- */
-import { asList, emitStateStructured, filterByFieldValue, formatEntry, loadArtifact, missingSchemaError, printStatusCounts, sourceMetadata, statusCounts, structuredState, truncate, } from "../../stateQuery.js";
-import { artifactPath, discoverSchemasDir } from "../../appContext.js";
 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 { out, err } from "./shared.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 o = out(io);
-    const e = err(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) {
-        e(missingSchemaError("docs") + "\n");
-        return 1;
-    }
-    const p = artifactPath(info, "docs");
-    const data = loadArtifact(p);
-    const format = args.format ?? "text";
-    const isDict = data !== null && typeof data === "object" && !Array.isArray(data);
-    if (!isDict) {
-        if (format !== "text") {
-            return emitStateStructured("docs", structuredState("docs", [], sourceMetadata("docs", p), {
-                filters: { topic: args.topic ?? null, status: args.status ?? null },
-            }), format, args.fields, o, e);
-        }
-        return 0;
-    }
-    const d = data;
-    const legacyEntries = asList(d.entries);
-    if (legacyEntries.length > 0) {
-        let entries = legacyEntries;
-        const statusFilter = args.status ?? null;
-        if (statusFilter)
-            entries = filterByFieldValue(entries, "status", statusFilter);
-        if (format !== "text") {
-            return emitStateStructured("docs", structuredState("docs", entries, sourceMetadata("docs", p), { filters: { status: statusFilter } }), format, args.fields, o, e);
-        }
-        for (const entry of entries) {
-            const line = formatEntry(entry, ["last_audit", "document", "path", "status"]);
-            if (line)
-                o(line + "\n");
+    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;
     }
-    const mapping = asList(d.mapping);
-    let index = asList(d.index);
-    const coverage = d.coverage && typeof d.coverage === "object" && !Array.isArray(d.coverage) ? d.coverage : {};
-    const conventions = d.conventions && typeof d.conventions === "object" && !Array.isArray(d.conventions) ? d.conventions : {};
-    const topic = args.topic ?? null;
-    if (topic) {
-        const t = topic.toLowerCase();
-        index = index.filter((entry) => String(entry.document ?? "").toLowerCase().includes(t) ||
-            String(entry.path ?? "").toLowerCase().includes(t) ||
-            String(entry.status ?? "").toLowerCase().includes(t));
-    }
-    const statusFilter = args.status ?? null;
-    if (statusFilter)
-        index = filterByFieldValue(index, "status", statusFilter);
-    if (format !== "text") {
-        return emitStateStructured("docs", structuredState("docs", index, sourceMetadata("docs", p), {
-            filters: { topic, status: statusFilter },
-            summary: {
-                last_audit: d.last_audit,
-                conventions,
-                mapping,
-                mapping_entries: mapping.length,
-                coverage,
-                source_contract: {
-                    capability_startup_complete: capabilityStartupComplete({ profileStatus }),
-                    raw_artifact_reads_required: false,
-                },
-            },
-        }), format, args.fields, o, e);
-    }
-    o(`Docs: last_audit=${d.last_audit ?? "-"}\n`);
-    o(`Mapping: entries=${mapping.length}\n`);
-    if (Object.keys(coverage).length > 0) {
-        o("Coverage: " + Object.entries(coverage).map(([k, v]) => `${k}=${truncate(v)}`).join(" | ") + "\n");
-    }
-    printStatusCounts("Docs status", statusCounts(index), o);
-    for (const entry of index.slice(0, 10)) {
-        const line = formatEntry(entry, ["document", "path", "last_updated", "status"]);
-        if (line)
-            o(line + "\n");
+    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;
     }
-    return 0;
 }
-//# sourceMappingURL=docs.js.map

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

@@ -1,68 +1,14 @@
-/**
- * `state experiments` query (experiments.yaml).
- *
- * Returns the most recent N experiments (default 5) filtered by
- * topic or status, including per-entry metric and conclusion.
- */
-import { asList, emitStateStructured, filterByFieldValue, filterByTopic, formatEntry, loadArtifact, missingSchemaError, printStatusCounts, sourceMetadata, statusCounts, structuredState, truncate, } from "../../stateQuery.js";
-import { artifactPath } from "../../appContext.js";
-import { out, err } from "./shared.js";
-export function queryExperiments(args, schemas, io) {
-    const o = out(io);
-    const e = err(io);
-    const info = schemas.experiments;
-    if (!info) {
-        e(missingSchemaError("experiments") + "\n");
-        return 1;
-    }
-    const p = artifactPath(info, "experiments");
-    const data = loadArtifact(p);
+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 isDict = data !== null && typeof data === "object" && !Array.isArray(data);
-    if (!isDict) {
-        if (format !== "text") {
-            return emitStateStructured("experiments", structuredState("experiments", [], sourceMetadata("experiments", p), {
-                filters: { topic: args.topic ?? null, status: args.status ?? null, limit: args.limit ?? 5 },
-            }), format, args.fields, o, e);
-        }
-        return 0;
-    }
-    // cast: data is the parsed experiments artifact from loadArtifact (YAML IO boundary)
-    const d = data;
-    let entries = asList(d.experiments);
-    const statusFilter = args.status ?? null;
-    if (statusFilter)
-        entries = filterByFieldValue(entries, "status", statusFilter);
-    const topic = args.topic ?? null;
-    if (topic)
-        entries = filterByTopic(entries, topic, info.fields);
-    const limit = (args.limit ?? 5) || 5;
-    entries = entries.slice(-limit);
-    const closure = d.closure && typeof d.closure === "object" && !Array.isArray(d.closure) ? d.closure : {};
-    if (format !== "text") {
-        return emitStateStructured("experiments", structuredState("experiments", entries, sourceMetadata("experiments", p), {
-            filters: { topic, status: statusFilter, limit },
-            summary: { closure },
-        }), format, args.fields, o, e);
-    }
-    printStatusCounts("Experiment status", statusCounts(entries), o);
-    for (const entry of entries) {
-        o(formatEntry(entry, ["number", "date", "label", "status"]) + "\n");
-        const metric = entry.metric;
-        if (metric && typeof metric === "object" && !Array.isArray(metric)) {
-            const metricLine = formatEntry(metric, ["primary_value", "delta_vs_baseline"]);
-            if (metricLine)
-                o(`  metric: ${metricLine}\n`);
-        }
-        for (const key of ["conclusion", "next"]) {
-            const value = entry[key];
-            if (value)
-                o(`  ${key}: ${truncate(value)}\n`);
-        }
-    }
-    if (Object.keys(closure).length > 0) {
-        o("Closure: " + formatEntry(closure, ["final_value", "target", "reason"]) + "\n");
-    }
+    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;
 }
-//# sourceMappingURL=experiments.js.map