agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/cli/migrationRequired.js

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import { emitStructured } from "./structured.js";
+import { classifyProjectState, detectStateMode } from "../state/stateMode.js";
+import { commandText, fullEntityUpgradeCommand, fullEntityUpgradePreviewCommand } from "../upgrade/upgradeCommands.js";
+import { preCutoverCommand } from "./preCutoverCommand.js";
+function value(argv, flag) {
+    const equals = argv.find((arg) => typeof arg === "string" && arg.startsWith(`${flag}=`));
+    if (equals)
+        return equals.slice(flag.length + 1);
+    const index = argv.indexOf(flag);
+    return index >= 0 ? argv[index + 1] : undefined;
+}
+export function requestedMigrationFailureFormat(argv) {
+    const format = value(argv, "--format");
+    return format === "json" || format === "yaml" ? format : "text";
+}
+/** Marker-absent projects expose only the forward upgrade and static discovery. */
+export function requiresCompletedEntityCutover(argv) {
+    const [command, subcommand, verb] = argv;
+    if (["--version", "version", "app-home", "doctor", "schema", "route", "upgrade"].includes(command))
+        return false;
+    if (command === "report" && ["profile-glossary", "profile-grounding"].includes(subcommand))
+        return false;
+    if (command === "prime" && (argv.includes("--guidance") || !argv.includes("--context") || value(argv, "--context") === "status"))
+        return false;
+    if (command === "query")
+        return !argv.includes("--list-artifacts");
+    if (command === "state" && subcommand === "query" && argv.includes("--list-artifacts"))
+        return false;
+    if (command === "state" && verb === "explain")
+        return false;
+    return true;
+}
+export function migrationProject(argv, fallback = process.cwd()) {
+    const explicit = value(argv, "--project");
+    if (explicit)
+        return path.resolve(explicit);
+    let candidate = path.resolve(fallback);
+    while (true) {
+        if (fs.existsSync(path.join(candidate, ".agentera", "state-mode.yaml")))
+            return candidate;
+        const parent = path.dirname(candidate);
+        if (parent === candidate)
+            return path.resolve(fallback);
+        candidate = parent;
+    }
+}
+function permitsFreshPlanInitialization(argv) {
+    const [command, subcommand, verb] = argv;
+    return command === "state" && subcommand === "plan" && verb === "create"
+        || command === "prime" && value(argv, "--context") === "plan";
+}
+function freshPlanCreateCommand(project) {
+    return commandText([
+        "npx", "-y", "agentera@next", "state", "plan", "create", "--project", project,
+        "--input", "PLAN.yaml", "--format", "json",
+    ]);
+}
+/** Read-only cutover gate. It only inspects the durable marker and emits a failure. */
+export function enforceCompletedEntityCutover(projectRoot, format, io = {}, argv = []) {
+    const project = path.resolve(projectRoot);
+    let mode;
+    try {
+        mode = detectStateMode(project);
+    }
+    catch (error) {
+        const recovery = `Restore the exact durable migration marker, then run ${preCutoverCommand("check validate state --format json")}.`;
+        const envelope = {
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: { class: "invalid_state_marker", message: error.message, project, recovery },
+        };
+        if (format === "json" || format === "yaml")
+            emitStructured(envelope, format, io.out ?? ((text) => process.stdout.write(text)));
+        else
+            (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${envelope.error.message}\nRecovery: ${recovery}\n`);
+        return 1;
+    }
+    if (mode === "entities")
+        return null;
+    const classification = classifyProjectState(project);
+    if (classification.state === "fresh_uninitialized") {
+        if (permitsFreshPlanInitialization(argv))
+            return null;
+        const recovery = freshPlanCreateCommand(project);
+        const envelope = {
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: {
+                class: "fresh_initialization_required",
+                message: "Fresh project state is initialized only by state plan create; no other state writer can create entity authority.",
+                project,
+                recovery,
+            },
+        };
+        if (format === "json" || format === "yaml")
+            emitStructured(envelope, format, io.out ?? ((text) => process.stdout.write(text)));
+        else
+            (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${envelope.error.message}\nRecovery: ${recovery}\n`);
+        return 1;
+    }
+    const legacy = classification.state === "legacy";
+    const recovery = legacy ? fullEntityUpgradeCommand(project) : fullEntityUpgradePreviewCommand(project);
+    const envelope = {
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "migration_required",
+            message: legacy
+                ? "This command requires the completed entity-state cutover; legacy aggregates remain migration input only."
+                : `This command cannot adopt marker-absent ${classification.state} Agentera state; inspect it with the read-only recovery command before any mutation.`,
+            project,
+            recovery,
+        },
+    };
+    if (format === "json" || format === "yaml")
+        emitStructured(envelope, format, io.out ?? ((text) => process.stdout.write(text)));
+    else
+        (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${envelope.error.message}\nRecovery: ${recovery}\n`);
+    return 1;
+}

package/dist/cli/orientation/attention.js

@@ -0,0 +1,61 @@
+import { projectIntegrationAttention } from "../../upgrade/projectIntegration.js";
+import { corpusCoverageAttention } from "./corpusCoverage.js";
+import { firstPresent } from "../stateQuery.js";
+import { TODO_SEVERITY_ORDER } from "../todoSeverity.js";
+export function buildOrientationAttention(state) {
+    const { v1_migration: v1Migration, project_integration: projectIntegration, health, plan, decision_attention: decisionAttention, glossary_caveat_attention: glossaryCaveatAttention, corpus_coverage: corpusCoverage, todo_items: todoItems, todo_reconciliation: todoReconciliation, } = state;
+    const attention = [];
+    if (todoReconciliation?.status === "action_required") {
+        const label = todoReconciliation.state === "inactive" ? "inactive" : todoReconciliation.state === "unsafe_inactive" ? "unsafe inactive" : todoReconciliation.state === "unsafe_active" ? "unsafe active" : "invalid lifecycle";
+        attention.push(todoReconciliation.state === "unsafe_inactive"
+            ? `action-required: TODO reconciliation is ${label}; ${todoReconciliation.recovery_command}`
+            : `action-required: TODO reconciliation is ${label}; preview \`${todoReconciliation.preview_command ?? "n/a"}\`; apply \`${todoReconciliation.apply_command ?? "n/a"}\``);
+    }
+    const skillDivergenceSignals = (state.app.signals ?? []).filter((s) => s.kind === "skill_root_divergence");
+    for (const signal of skillDivergenceSignals) {
+        attention.push(`degraded: skill-root divergence — ${signal.message ?? "a recognized skill root is below expected"}; run \`npx -y agentera@next upgrade --dry-run --channel development\` to preview repair (D78)`);
+    }
+    const integrationAttention = projectIntegrationAttention(projectIntegration);
+    const hasAppIntegration = (projectIntegration.phases?.app.counts.total ?? 0) > 0;
+    const includeIntegrationAttention = Boolean(integrationAttention && hasAppIntegration);
+    if (includeIntegrationAttention && integrationAttention) {
+        attention.push(integrationAttention);
+    }
+    const coverageAttention = corpusCoverageAttention(corpusCoverage);
+    if (coverageAttention) {
+        attention.push(coverageAttention);
+    }
+    if (v1Migration.detected && projectIntegration.recommendation !== "upgrade") {
+        attention.push(`degraded: v1 artifacts detected; preview \`${v1Migration.dry_run_command}\`; files=${v1Migration.affected_files.join(", ")}`);
+    }
+    if (health.stale) {
+        const auditId = health.id ?? "unknown";
+        const daysSince = health.days_since_audit ?? "?";
+        const thresholdDays = health.stale_threshold_days ?? "?";
+        const thresholdCycles = health.stale_threshold_cycles ?? "?";
+        let attentionText = `normal: audit stale (${daysSince} days since health audit ${auditId}; ` +
+            `threshold days=${thresholdDays}, cycles=${thresholdCycles}`;
+        const cyclesSince = health.cycles_since_audit;
+        if (cyclesSince !== null && cyclesSince !== undefined)
+            attentionText += `; ${cyclesSince} cycles since audit`;
+        attention.push(`${attentionText}); suggest running audit`);
+    }
+    if (health.degrading) {
+        const worst = health.worst;
+        attention.push(worst ? `critical: health needs attention (${worst[0]}:${worst[1]})` : "critical: health is degrading");
+    }
+    if (glossaryCaveatAttention)
+        attention.push(glossaryCaveatAttention);
+    const pending = plan.first_pending;
+    if (pending && typeof pending === "object" && !Array.isArray(pending)) {
+        const title = firstPresent(pending, ["name", "title"], "pending task");
+        attention.push(`normal: PLAN Task ${pending.number ?? "?"}: ${title}`);
+    }
+    if (decisionAttention !== null)
+        attention.push(String(decisionAttention.attention));
+    if (!(pending && typeof pending === "object" && !Array.isArray(pending)) && todoItems.length > 0) {
+        const firstTodo = [...todoItems].sort((a, b) => (TODO_SEVERITY_ORDER[String(a.severity)] ?? 2) - (TODO_SEVERITY_ORDER[String(b.severity)] ?? 2))[0];
+        attention.push(`${String(firstTodo.severity)}: TODO: ${String(firstTodo.text)}`);
+    }
+    return attention;
+}

package/dist/cli/orientation/corpusCoverage.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import { corpusTooLargeReason } from "../../analytics/usageStats.js";
+import { statsCorpusPath } from "../commands/report.js";
+import { tiersDirForCorpusPath, assessTiers, readBoundedMetadata, } from "../../analytics/extractCorpus/index.js";
+function emptyCoverageSummary(path, status) {
+    return {
+        path,
+        status,
+        available_runtimes: [],
+        selected_runtimes: [],
+        available_but_not_selected: [],
+    };
+}
+function parseCoverageGap(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const item = value;
+    const runtime = item.runtime;
+    const reason = item.reason;
+    if (typeof runtime !== "string" || typeof reason !== "string")
+        return null;
+    const gap = { runtime, reason };
+    if (typeof item.store_path === "string")
+        gap.store_path = item.store_path;
+    return gap;
+}
+export function corpusCoverageSummary(env = process.env, platform = process.platform) {
+    const corpusPath = statsCorpusPath(env, platform);
+    const tiersDir = tiersDirForCorpusPath(corpusPath);
+    const assessment = assessTiers(tiersDir, corpusPath);
+    // Bounded tier coverage: when tiers are published, the manifest's coverage
+    // envelope truthfully reports the audit's available/selected/skipped runtimes
+    // without reading full evidence. The signal tier (bounded) remains usable even
+    // when a full-evidence shard is oversized, per the authority contract.
+    if (assessment.state !== "legacy" && assessment.state !== "missing") {
+        const meta = readBoundedMetadata(tiersDir);
+        const envelope = meta.corpusMetadata?.coverage_envelope;
+        if (meta.signal && envelope) {
+            return {
+                path: corpusPath,
+                tier_path: tiersDir,
+                status: "loaded",
+                tier_state: assessment.state,
+                available_runtimes: [...envelope.available_runtimes],
+                selected_runtimes: [...envelope.selected_runtimes],
+                available_but_not_selected: envelope.available_but_not_selected.map((g) => ({
+                    runtime: g.runtime,
+                    reason: g.reason,
+                    ...(typeof g.store_path === "string" ? { store_path: g.store_path } : {}),
+                })),
+            };
+        }
+        if (assessment.state === "oversized")
+            return emptyCoverageSummary(corpusPath, "too_large");
+        if (assessment.state === "corrupt")
+            return emptyCoverageSummary(corpusPath, "unreadable");
+    }
+    // Legacy monolithic envelope: small state preserved for compatibility.
+    if (!fs.existsSync(corpusPath))
+        return emptyCoverageSummary(corpusPath, "missing");
+    const tooLarge = corpusTooLargeReason(corpusPath);
+    if (tooLarge)
+        return emptyCoverageSummary(corpusPath, "too_large");
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(corpusPath, "utf8"));
+    }
+    catch {
+        return emptyCoverageSummary(corpusPath, "unreadable");
+    }
+    const metadata = data && typeof data === "object" && !Array.isArray(data) && "metadata" in data
+        ? data.metadata
+        : null;
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return emptyCoverageSummary(corpusPath, "unreadable");
+    }
+    const md = metadata;
+    const availableRuntimes = Array.isArray(md.available_runtimes)
+        ? md.available_runtimes.filter((item) => typeof item === "string")
+        : [];
+    const selectedRuntimes = Array.isArray(md.selected_runtimes)
+        ? md.selected_runtimes.filter((item) => typeof item === "string")
+        : [];
+    const skipped = Array.isArray(md.available_but_not_selected)
+        ? md.available_but_not_selected.map(parseCoverageGap).filter((item) => item !== null)
+        : [];
+    return {
+        path: corpusPath,
+        status: "loaded",
+        tier_state: "legacy",
+        available_runtimes: availableRuntimes,
+        selected_runtimes: selectedRuntimes,
+        available_but_not_selected: skipped,
+    };
+}
+export function corpusCoverageAttention(summary) {
+    if (summary.available_but_not_selected.length === 0)
+        return null;
+    const skipped = summary.available_but_not_selected.map((item) => `${item.runtime} (${item.reason})`).join(", ");
+    return (`flagged: corpus coverage loss (EX2): available runtimes skipped (${skipped}); ` +
+        "suggest running profile stats refresh without --no-* flags");
+}