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

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

@@ -0,0 +1,129 @@
+import YAML from "yaml";
+import { resolveSourceRoot } from "../../../core/sourceRoot.js";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { getDecisionEntity } from "../../../state/decisionEntities.js";
+import { getHealthEntity } from "../../../state/healthEntities.js";
+import { getObjectiveEntity } from "../../../state/objectiveExperimentEntities.js";
+import { getProgressEntity } from "../../../state/progressEntities.js";
+import { getTodoDocsEntity } from "../../../state/todoDocsEntities.js";
+import { emitStructured } from "../../structured.js";
+import { entityListFamily } from "../../../state/entityRetrievalHelp.js";
+import { runtimeGenericEntityListFamily } from "../../../state/entityListRuntimeRegistry.js";
+function requestedFormat(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--format") {
+            const value = argv[index + 1];
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+        if (token.startsWith("--format=")) {
+            const value = token.slice("--format=".length);
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+    }
+    return "text";
+}
+function failure(message, id, artifact = "progress") {
+    const runtime = runtimeGenericEntityListFamily(artifact);
+    const family = runtime ? entityListFamily(runtime.key) : undefined;
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "invalid_request",
+            message,
+            syntax: family?.get ?? `agentera state ${artifact} get --id ID --format json`,
+            example: `agentera state ${artifact} get --id ${id ?? "qjtrmnpvka"} --format json`,
+            recovery: `Use a bare ten-letter ${artifact} ID returned by append or list; no state was changed.`,
+            artifact,
+            ...(id ? { id } : {}),
+        },
+    }, 2);
+}
+function readValue(argv, index, name) {
+    const token = argv[index];
+    if (token.startsWith(`${name}=`))
+        return { value: token.slice(name.length + 1), next: index + 1 };
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return { value, next: index + 2 };
+}
+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}`,
+            `Syntax: ${detail.syntax}`,
+            `Example: ${detail.example}`,
+            `Recovery: ${detail.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return error.exitCode;
+}
+export function runStateGet(artifactId, argv, io, projectRoot = process.cwd()) {
+    const format = requestedFormat(argv);
+    const sourceRoot = resolveSourceRoot();
+    try {
+        if (!runtimeGenericEntityListFamily(artifactId))
+            throw failure(`unsupported state artifact '${artifactId}'`, undefined, artifactId);
+        let id;
+        let entityFormat = "text";
+        let formatSupplied = false;
+        for (let index = 0; index < argv.length;) {
+            const token = argv[index];
+            if (token !== "--id" && !token.startsWith("--id=") && token !== "--format" && !token.startsWith("--format=")) {
+                throw failure(`unrecognized argument '${token}'; entity-mode ${artifactId} retrieval requires --id ID`, id, artifactId);
+            }
+            const name = token.startsWith("--id") ? "--id" : "--format";
+            let parsed;
+            try {
+                parsed = readValue(argv, index, name);
+            }
+            catch (error) {
+                throw failure(error.message, id, artifactId);
+            }
+            index = parsed.next;
+            if (name === "--id") {
+                if (id !== undefined)
+                    throw failure("--id may only be supplied once", id, artifactId);
+                id = parsed.value;
+            }
+            else {
+                if (formatSupplied)
+                    throw failure("--format may only be supplied once", id, artifactId);
+                formatSupplied = true;
+                if (parsed.value !== "text" && parsed.value !== "json" && parsed.value !== "yaml")
+                    throw failure(`invalid --format '${parsed.value}'`, id, artifactId);
+                entityFormat = parsed.value;
+            }
+        }
+        if (!id)
+            throw failure(`--id is required for entity-mode ${artifactId} retrieval`, id, artifactId);
+        const response = artifactId === "progress"
+            ? getProgressEntity(projectRoot, id, sourceRoot)
+            : artifactId === "decisions"
+                ? getDecisionEntity(projectRoot, id, sourceRoot)
+                : artifactId === "health"
+                    ? getHealthEntity(projectRoot, id, sourceRoot)
+                    : artifactId === "objective"
+                        ? getObjectiveEntity(projectRoot, id, sourceRoot)
+                        : getTodoDocsEntity(projectRoot, artifactId, id, sourceRoot);
+        const output = io.out ?? ((text) => process.stdout.write(text));
+        if (entityFormat === "json" || entityFormat === "yaml")
+            emitStructured(response, entityFormat, output);
+        else
+            output(YAML.stringify(response));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof StateRetrievalFailure)
+            return emitFailure(error, format, io);
+        return emitFailure(failure(error.message, undefined, artifactId), format, io);
+    }
+}

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

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

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

@@ -0,0 +1,16 @@
+/**
+ * Public surface for the `state <name>` command family.
+ *
+ * Record-family retrieval dispatch is owned by entityListRuntimeRegistry.
+ * This module retains the specialized projections used by startup collectors
+ * and compatibility code; it does not enumerate public retrieval routes.
+ */
+import { queryProgress } from "./progress.js";
+import { queryPlan } from "./plan.js";
+import { queryHealth } from "./health.js";
+import { queryDocs } from "./docs.js";
+import { queryObjective } from "./objective.js";
+import { queryExperiments } from "./experiments.js";
+import { queryTodo, normalizeSeverity } from "./todo.js";
+import { queryDecisions, decisionContextEntry, decisionSatisfactionContext, decisionSourceContract, extractDecisionEntries, hydrateDecisionEntries, displayFields, } from "./decisions.js";
+export { queryProgress, queryPlan, queryHealth, queryDocs, queryObjective, queryExperiments, queryTodo, queryDecisions, normalizeSeverity, decisionContextEntry, decisionSatisfactionContext, decisionSourceContract, extractDecisionEntries, hydrateDecisionEntries, displayFields, };

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

@@ -0,0 +1,194 @@
+import { resolveSourceRoot } from "../../../core/sourceRoot.js";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { emitStructured } from "../../structured.js";
+import { listProgressEntities, renderProgressEntityListText } from "../../../state/progressEntities.js";
+import { listDecisionEntities } from "../../../state/decisionEntities.js";
+import { listHealthEntities } from "../../../state/healthEntities.js";
+import { listObjectiveEntities } from "../../../state/objectiveExperimentEntities.js";
+import { listTodoDocsEntities } from "../../../state/todoDocsEntities.js";
+import YAML from "yaml";
+import { entityListFamilies, entityListValidValues } from "../../../state/entityRetrievalHelp.js";
+import { ENTITY_LIST_RUNTIME_FAMILIES, runtimeGenericEntityListFamily } from "../../../state/entityListRuntimeRegistry.js";
+function requestedFormat(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--format") {
+            const value = argv[index + 1];
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+        if (token.startsWith("--format=")) {
+            const value = token.slice("--format=".length);
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+    }
+    return "text";
+}
+function syntax(artifactId) {
+    return `agentera state ${artifactId} list [--limit N] [--cursor TOKEN] --format json`;
+}
+function failure(className, artifactId, message, example = `agentera state ${artifactId} list --limit 20 --format json`, validValues) {
+    const family = entityListFamilies().find(({ key }) => key === artifactId);
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: className,
+            message,
+            syntax: family?.syntax ?? syntax(artifactId),
+            example: family?.example ?? example,
+            recovery: family ? `Run \`${family.example}\`; no state was changed.` : "Correct the command using the valid syntax and retry; no state was changed.",
+            artifact_id: artifactId,
+            ...(validValues ? { valid_values: validValues } : family ? { valid_values: entityListValidValues(family) } : {}),
+        },
+    }, 2);
+}
+function readValue(argv, index, name) {
+    const token = argv[index];
+    if (token.startsWith(`${name}=`))
+        return { value: token.slice(name.length + 1), next: index + 1 };
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return { value, next: index + 2 };
+}
+function parseListArgs(artifactId, argv) {
+    const runtime = runtimeGenericEntityListFamily(artifactId);
+    if (!runtime) {
+        const validValues = ENTITY_LIST_RUNTIME_FAMILIES.map(({ commandTokens }) => commandTokens.join(" "));
+        throw failure("unsupported_artifact", artifactId, `unsupported state artifact '${artifactId}'`, undefined, validValues);
+    }
+    const family = entityListFamilies().find(({ key }) => key === runtime.key);
+    let limit = family.bounds.default;
+    let cursor;
+    let format = "text";
+    const filters = {};
+    const selector = {};
+    const allowedFilters = new Set(family.filters.map(({ name }) => `--${name}`));
+    let limitSupplied = false;
+    let cursorSupplied = false;
+    let formatSupplied = false;
+    const filterSupplied = new Set();
+    for (let index = 0; index < argv.length;) {
+        const token = argv[index];
+        if (token === "--ids-only") {
+            if (selector.idsOnly)
+                throw failure("invalid_request", artifactId, "--ids-only may only be supplied once");
+            selector.idsOnly = true;
+            index += 1;
+            continue;
+        }
+        const matches = (flag) => token === flag || token.startsWith(`${flag}=`);
+        const name = matches("--limit") ? "--limit" : matches("--cursor") ? "--cursor" : matches("--format") ? "--format" : matches("--fields") ? "--fields" : [...allowedFilters].find(matches) ?? null;
+        if (!name)
+            throw failure("invalid_request", artifactId, `unrecognized argument '${token}'`);
+        let parsed;
+        try {
+            parsed = readValue(argv, index, name);
+        }
+        catch (error) {
+            throw failure("invalid_request", artifactId, error.message);
+        }
+        index = parsed.next;
+        if (name === "--limit") {
+            if (limitSupplied)
+                throw failure("invalid_request", artifactId, "--limit may only be supplied once");
+            limitSupplied = true;
+            if (!/^[1-9][0-9]*$/.test(parsed.value))
+                throw failure("invalid_request", artifactId, `argument --limit must be a positive canonical integer from ${family.bounds.minimum} through ${family.bounds.maximum}`);
+            limit = Number(parsed.value);
+            if (!Number.isSafeInteger(limit) || limit < family.bounds.minimum || limit > family.bounds.maximum)
+                throw failure("invalid_request", artifactId, `argument --limit must be between ${family.bounds.minimum} and ${family.bounds.maximum}`);
+        }
+        else if (name === "--cursor") {
+            if (cursorSupplied)
+                throw failure("invalid_request", artifactId, "--cursor may only be supplied once");
+            cursorSupplied = true;
+            if (parsed.value.length === 0)
+                throw failure("invalid_request", artifactId, "argument --cursor must be a non-empty opaque token");
+            cursor = parsed.value;
+        }
+        else if (name === "--fields") {
+            if (selector.fields !== undefined)
+                throw failure("invalid_request", artifactId, "--fields may only be supplied once");
+            selector.fields = parsed.value;
+        }
+        else {
+            if (name !== "--format") {
+                if (filterSupplied.has(name))
+                    throw failure("invalid_request", artifactId, `${name} may only be supplied once`);
+                filterSupplied.add(name);
+                const key = name.slice(2);
+                filters[key] = parsed.value;
+                continue;
+            }
+            if (formatSupplied)
+                throw failure("invalid_request", artifactId, "--format may only be supplied once");
+            formatSupplied = true;
+            if (!family.formats.includes(parsed.value)) {
+                throw failure("invalid_request", artifactId, `argument --format: invalid choice: '${parsed.value}' (choose from ${family.formats.map((value) => `'${value}'`).join(", ")})`);
+            }
+            format = parsed.value;
+        }
+    }
+    return { limit, ...(cursor ? { cursor } : {}), format, filters, selector };
+}
+function emitFailure(error, format, io) {
+    const out = io.out ?? ((text) => process.stdout.write(text));
+    if (format === "json" || format === "yaml")
+        emitStructured(error.body, format, out);
+    else {
+        const details = error.body.error;
+        (io.err ?? ((text) => process.stderr.write(text)))([
+            `Error: ${details.message}`,
+            `Class: ${details.class}`,
+            `Syntax: ${details.syntax}`,
+            `Valid values: ${(details.valid_values ?? []).join("; ")}`,
+            `Example: ${details.example}`,
+            `Recovery: ${details.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return error.exitCode;
+}
+export function runStateList(artifactId, argv, io, projectRoot = process.cwd()) {
+    const format = requestedFormat(argv);
+    const sourceRoot = resolveSourceRoot();
+    try {
+        const args = parseListArgs(artifactId, argv);
+        const response = artifactId === "progress"
+            ? listProgressEntities(projectRoot, args.limit, args.filters, args.cursor, { sourceRoot, format: args.format, selector: args.selector })
+            : artifactId === "decisions"
+                ? listDecisionEntities(projectRoot, args.limit, args.filters.topic ?? undefined, args.cursor, { sourceRoot, format: args.format, selector: args.selector })
+                : artifactId === "health"
+                    ? listHealthEntities(projectRoot, args.limit, args.filters.dimension ?? undefined, args.cursor, { sourceRoot, format: args.format, selector: args.selector })
+                    : artifactId === "objective"
+                        ? listObjectiveEntities(projectRoot, args.limit, args.cursor, { sourceRoot, format: args.format, selector: args.selector })
+                        : listTodoDocsEntities(projectRoot, artifactId, args.limit, args.cursor, args.filters, { sourceRoot, format: args.format, selector: args.selector });
+        const output = io.out ?? ((text) => process.stdout.write(text));
+        if (args.format === "text")
+            output(artifactId === "progress" ? renderProgressEntityListText(response) : YAML.stringify(response));
+        else
+            emitStructured(response, args.format, output);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof StateRetrievalFailure) {
+            const body = structuredClone(error.body);
+            delete body.error.artifact_id;
+            body.error.artifact = artifactId;
+            return emitFailure(new StateRetrievalFailure(body, error.exitCode), format, io);
+        }
+        return emitFailure(new StateRetrievalFailure({
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: {
+                class: "unsupported_state",
+                message: error.message,
+                syntax: syntax(artifactId),
+                example: `agentera state ${artifactId} list --limit 20 --format json`,
+                recovery: "Use a state format supported by the storage authority, then retry.",
+            },
+        }, 1), format, io);
+    }
+}

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

@@ -0,0 +1,25 @@
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { currentObjectiveEntity } from "../../../state/objectiveExperimentEntities.js";
+import { emitStructured } from "../../structured.js";
+import { formatEntry } from "../../stateQuery.js";
+import { err, out } from "./shared.js";
+export function queryObjective(args, _schemas, io) {
+    const output = out(io);
+    try {
+        const response = currentObjectiveEntity(process.cwd());
+        if (args.format === "json" || args.format === "yaml")
+            emitStructured(response, args.format, output);
+        else
+            output(formatEntry(response.entries[0], ["id", "artifact"]) + "\n");
+        return 0;
+    }
+    catch (error) {
+        if (!(error instanceof StateRetrievalFailure))
+            throw error;
+        if (args.format === "json" || args.format === "yaml")
+            emitStructured(error.body, args.format, output);
+        else
+            err(io)(`Error: ${error.body.error.message}\nRecovery: ${error.body.error.recovery}\n`);
+        return error.exitCode;
+    }
+}

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

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

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

@@ -0,0 +1,154 @@
+import YAML from "yaml";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { getPlanTaskEntity, listPlanTaskEntities } from "../../../state/planEntities.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 readValue(argv, index, name) {
+    const token = argv[index];
+    if (token.startsWith(`${name}=`))
+        return { value: token.slice(name.length + 1), next: index + 1 };
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return { value, next: index + 2 };
+}
+function failure(message, verb) {
+    const list = verb === "list";
+    const family = entityListFamily("plan_tasks");
+    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 plan tasks get --id qjtrmnpvka --format json",
+            recovery: list ? `Run \`${family.example}\`; no state was changed.` : "Correct the command using one of the valid forms and retry; no state was changed.",
+            valid_values: list
+                ? entityListValidValues(family)
+                : ["get", "--id ID", "--format text|json|yaml"],
+        },
+    }, 2);
+}
+function parse(argv, verb) {
+    const family = entityListFamily("plan_tasks");
+    let format = "text";
+    let plan;
+    let limit = family.bounds.default;
+    let cursor;
+    let id;
+    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;
+        }
+        if (verb === "list" && !token.startsWith("--")) {
+            if (plan)
+                throw failure(`unrecognized argument '${token}'`, verb);
+            plan = token;
+            index += 1;
+            continue;
+        }
+        const allowed = verb === "list" ? ["--format", "--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 = readValue(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 === "--limit") {
+            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);
+        }
+        else if (name === "--cursor")
+            cursor = parsed.value;
+        else if (name === "--fields")
+            selector.fields = parsed.value;
+        else
+            id = parsed.value;
+    }
+    if (verb === "get" && !id)
+        throw failure("entity mode requires a bare ten-letter --id selector", verb);
+    return { format, limit, ...(plan ? { plan } : {}), ...(cursor ? { cursor } : {}), ...(id ? { id } : {}), 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 runPlanTasks(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"
+            ? listPlanTaskEntities(process.cwd(), args.plan, args.limit, args.cursor, { format: args.format, selector: args.selector })
+            : getPlanTaskEntity(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 plan tasks {list|get} [options]",
+                example: "agentera state plan tasks list --format json",
+                recovery: "Use a supported active plan and retry; no state was changed.",
+            },
+        }, 1), format, io);
+    }
+}