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

package/dist/cli/capabilityContext/planState.js

@@ -0,0 +1,260 @@
+import { asList } from "../stateQuery.js";
+import { entryStatus, sourceProvenance, taskRef, hasRecordedValue, } from "./shared.js";
+import { planTaskIndex } from "../planTaskIndex.js";
+import { STATE_FAMILY_FALLBACK_COMMANDS } from "./types.js";
+import { boundedChangelogUnavailable, CHANGELOG_MAX_OUTPUT_BYTES, readChangelog, } from "../../state/changelog.js";
+export function orchestrationTaskSummary(task) {
+    const evidence = task.evidence;
+    const evidenceItems = Array.isArray(evidence) ? evidence : evidence === null || evidence === undefined || evidence === "" ? [] : [evidence];
+    return {
+        ...taskRef(task),
+        depends_on: planDependsOnList(task),
+        acceptance_summary: { count: asList(task.acceptance).length, items: asList(task.acceptance) },
+        evidence_summary: { count: evidenceItems.length, items: evidenceItems },
+        evaluation_state: task.evaluation ?? null,
+    };
+}
+/** Coerce canonical IDs and internal legacy task refs to comparable lookup keys. */
+export function planTaskRefKeys(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (typeof value === "object" && !Array.isArray(value)) {
+        const entry = value;
+        const nested = entry.number ?? entry.task_number ?? entry.id;
+        return nested === null || nested === undefined ? [] : planTaskRefKeys(nested);
+    }
+    const text = String(value).trim();
+    if (!text)
+        return [];
+    const keys = new Set([text]);
+    const numeric = Number(text);
+    if (Number.isFinite(numeric) && Number.isInteger(numeric))
+        keys.add(String(numeric));
+    return [...keys];
+}
+export function formatPlanTaskDepRef(dep) {
+    const keys = planTaskRefKeys(dep);
+    return keys.length > 0 ? keys[0] : String(dep);
+}
+export function planDependsOnList(task) {
+    const raw = task.depends_on;
+    if (Array.isArray(raw))
+        return raw;
+    if (raw === null || raw === undefined || raw === "")
+        return [];
+    return [raw];
+}
+export function indexPlanTasksByNumber(tasks) {
+    const taskByNumber = {};
+    for (const task of tasks) {
+        for (const value of [task.id, task.number]) {
+            for (const key of planTaskRefKeys(value))
+                taskByNumber[key] = task;
+        }
+    }
+    return taskByNumber;
+}
+export function resolvePlanTaskByRef(taskByNumber, dep) {
+    for (const key of planTaskRefKeys(dep)) {
+        const hit = taskByNumber[key];
+        if (hit !== undefined)
+            return hit;
+    }
+    return undefined;
+}
+export const DONE_STATUSES_ORCH = new Set(["complete", "completed", "closed", "done", "resolved", "retired", "superseded"]);
+export const BLOCKED_STATUSES_ORCH = new Set(["blocked", "stuck"]);
+export const TARGET_VERSION_RE = /\b\d+\.\d+\.\d+\b/;
+export const TARGET_VERSION_MAX_BYTES = 64;
+export function dependencyReadyTasks(tasks) {
+    const taskByNumber = indexPlanTasksByNumber(tasks);
+    const ready = [];
+    for (const task of tasks) {
+        const status = entryStatus(task, "pending");
+        if (status !== "pending")
+            continue;
+        let blocked = false;
+        for (const dep of planDependsOnList(task)) {
+            const dependency = resolvePlanTaskByRef(taskByNumber, dep);
+            if (dependency === undefined || !DONE_STATUSES_ORCH.has(entryStatus(dependency, "pending"))) {
+                blocked = true;
+                break;
+            }
+        }
+        if (!blocked)
+            ready.push(task);
+    }
+    return ready;
+}
+export function firstActionablePlanTask(tasks) {
+    return tasks.find((task) => entryStatus(task, "pending") === "in_progress")
+        ?? dependencyReadyTasks(tasks)[0]
+        ?? null;
+}
+export function selectEvidenceTarget(plan) {
+    const tasks = planTaskIndex(plan);
+    const noTarget = {
+        status: "no_target",
+        target_type: "repository",
+        task: null,
+        selection_reason: "no_plan_task_target",
+        source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "entries"),
+        caveats: ["No plan task target was selected; evaluate repository-level evidence only."],
+    };
+    if (!plan.exists || tasks.length === 0)
+        return noTarget;
+    const actionable = firstActionablePlanTask(tasks);
+    if (actionable) {
+        const inProgress = entryStatus(actionable, "pending") === "in_progress";
+        return {
+            status: "selected",
+            target_type: "plan_task",
+            task: taskRef(actionable),
+            selection_reason: inProgress
+                ? "in_progress_task"
+                : "first_dependency_ready_pending_task",
+            source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, inProgress ? "entries.status" : "entries.depends_on"),
+            caveats: [],
+        };
+    }
+    const completedWithEvidence = [...tasks].reverse().find((task) => DONE_STATUSES_ORCH.has(entryStatus(task, "pending")) && hasRecordedValue(task.evidence));
+    if (completedWithEvidence) {
+        return {
+            status: "selected",
+            target_type: "plan_task",
+            task: taskRef(completedWithEvidence),
+            selection_reason: "latest_completed_task_with_evidence",
+            source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "entries.evidence"),
+            caveats: [],
+        };
+    }
+    return noTarget;
+}
+export function taskByRef(plan, ref) {
+    if (!ref)
+        return null;
+    const tasks = planTaskIndex(plan);
+    return resolvePlanTaskByRef(indexPlanTasksByNumber(tasks), ref) ?? null;
+}
+export function planContextField(plan, field) {
+    const summary = plan.summary && typeof plan.summary === "object" && !Array.isArray(plan.summary) ? plan.summary : {};
+    return field in summary ? summary[field] : plan[field];
+}
+export function buildScopeBoundary(plan, selected) {
+    const explicitPaths = [];
+    const scopeField = planContextField(plan, "scope");
+    const sources = [selected ?? {}, scopeField && typeof scopeField === "object" ? scopeField : {}];
+    for (const source of sources) {
+        if (!source || typeof source !== "object" || Array.isArray(source))
+            continue;
+        for (const key of ["source_files", "files", "paths"]) {
+            for (const value of asList(source[key])) {
+                const text = String(value).trim();
+                if (text && !explicitPaths.includes(text))
+                    explicitPaths.push(text);
+            }
+        }
+    }
+    return {
+        artifact_families: ["plan", "progress", "todo", "docs", "health", "changelog", "decisions", "vision", "profile", "design"],
+        source_scope: {
+            status: explicitPaths.length > 0 ? "explicit" : "unspecified",
+            explicit_paths: explicitPaths,
+            policy: "Do not infer source-file allowlists or exclusions from task text; use only explicit plan/source-contract paths.",
+        },
+    };
+}
+export function buildArtifactUpdateRequirements(plan, docs) {
+    const mapping = asList(docs.mapping);
+    const mapped = mapping.filter((e) => e && typeof e === "object" && e.artifact).map((e) => e.artifact);
+    const archiveOnly = Boolean(plan.exists) && plan.active === false;
+    return {
+        required_families: archiveOnly ? [] : ["plan", "progress", "todo", "changelog"],
+        protected_families: ["vision", "objective", "profile", "installed_app"],
+        docs_mapping_available: Boolean(docs.exists && mapping.length > 0),
+        mapped_artifacts: mapped,
+        plan_status_update_required: plan.active === true,
+        policy: archiveOnly
+            ? "Archived plan history is non-executable and requires no execution artifact updates."
+            : "Update execution artifacts during the cycle; do not mutate protected state without explicit approval.",
+        source_provenance: sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs, "summary.mapping"),
+    };
+}
+export function buildPlanCompletionSweep(plan) {
+    const complete = plan.active === true && Boolean(plan.complete_plan);
+    return {
+        status: complete ? "eligible" : "not_eligible",
+        mutation_allowed: false,
+        required_updates: complete ? ["progress aggregate cycle", "changelog plan-level entries", "TODO milestone advance", "health cross-reference"] : [],
+        archive_candidate: complete ? "active plan archive path is generated only during Build sweep execution" : null,
+        caveats: complete
+            ? []
+            : plan.active === false && plan.exists
+                ? ["Archived plan history is non-executable and cannot trigger a completion sweep."]
+                : ["Plan completion sweep is not eligible until every plan task is complete."],
+        source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "summary.status"),
+    };
+}
+function selectedTargetVersionState(plan) {
+    const textParts = [String(plan.title ?? "")];
+    const firstPending = plan.first_pending;
+    if (firstPending && typeof firstPending === "object" && !Array.isArray(firstPending)) {
+        for (const key of ["name", "title"])
+            textParts.push(String(firstPending[key] ?? ""));
+    }
+    for (const task of asList(plan.tasks)) {
+        if (task && typeof task === "object" && !Array.isArray(task)) {
+            for (const key of ["name", "title"])
+                textParts.push(String(task[key] ?? ""));
+        }
+    }
+    const match = TARGET_VERSION_RE.exec(textParts.join("\n"));
+    if (!match)
+        return { value: null, boundExceeded: false };
+    if (Buffer.byteLength(match[0], "utf8") > TARGET_VERSION_MAX_BYTES) {
+        return { value: null, boundExceeded: true };
+    }
+    return { value: match[0], boundExceeded: false };
+}
+export function selectedTargetVersion(plan) {
+    return selectedTargetVersionState(plan).value;
+}
+function serializedProjectionBytes(projection) {
+    return Buffer.byteLength(`${JSON.stringify(projection, null, 2)}\n`, "utf8");
+}
+export function closeoutChangelogBoundary(projectRoot, plan) {
+    const shared = readChangelog(projectRoot);
+    const target = selectedTargetVersionState(plan);
+    const targetVersion = target.value;
+    const selectedRecorded = shared.projection.status === "available"
+        && targetVersion !== null
+        && shared.recognizedReleaseVersions.includes(targetVersion);
+    const caveats = [...(shared.projection.caveats ?? [])];
+    if (shared.projection.status === "available" && targetVersion && !selectedRecorded) {
+        caveats.push(`CHANGELOG state has no ${targetVersion} closeout entry yet.`);
+    }
+    if (target.boundExceeded) {
+        caveats.push("Selected target version is unavailable because its identity exceeds the supported bound.");
+    }
+    const boundary = {
+        ...shared.projection,
+        selected_target_version: targetVersion,
+        selected_target_recorded: selectedRecorded,
+        release_state: selectedRecorded ? "selected_target_recorded" : "no_selected_target_closeout_entry",
+        caveats,
+        recovery: shared.projection.recovery ?? null,
+    };
+    if (serializedProjectionBytes(boundary) <= CHANGELOG_MAX_OUTPUT_BYTES)
+        return boundary;
+    const bounded = boundedChangelogUnavailable("CHANGELOG closeout state is unavailable because its bounded target overlay exceeds the supported output limit.").projection;
+    const fallback = {
+        ...bounded,
+        selected_target_version: null,
+        selected_target_recorded: false,
+        release_state: "no_selected_target_closeout_entry",
+    };
+    if (serializedProjectionBytes(fallback) > CHANGELOG_MAX_OUTPUT_BYTES) {
+        throw new Error("fixed changelog closeout projection exceeds its output limit");
+    }
+    return fallback;
+}

package/dist/cli/capabilityContext/progress.js

@@ -0,0 +1,142 @@
+import { evaluatorHandoffOutputRequirements, loadEvaluatorHandoffContract, } from "../../registries/evaluatorHandoffContract.js";
+import { capabilityInstructionContractPath } from "./contract.js";
+import { hasRecordedValue, isFile, taskRef } from "./shared.js";
+import { STATE_FAMILY_LIST_COMMANDS } from "./types.js";
+export function progressVerificationSummary(progress) {
+    const source = { source_family: "progress", command: STATE_FAMILY_LIST_COMMANDS.progress };
+    if (!progress.exists) {
+        return {
+            status: "unavailable",
+            source_provenance: source,
+            cycle: null,
+            verified_present: false,
+            non_empty_evidence_present: false,
+            non_empty_evidence_fields: [],
+            verified: null,
+            verification_summary: null,
+            latest_progress_verification_pointer: null,
+            caveats: ["No progress cycles are recorded in CLI progress state."],
+        };
+    }
+    const latest = progress.latest && typeof progress.latest === "object" && !Array.isArray(progress.latest) ? progress.latest : {};
+    const verified = latest.verified;
+    const latestVerification = progress.latest_verification && typeof progress.latest_verification === "object" && !Array.isArray(progress.latest_verification)
+        ? progress.latest_verification
+        : {};
+    const projectedVerifiedPresent = latest.verified_present === true || latestVerification.present === true;
+    const verifiedPresent = hasRecordedValue(verified) || projectedVerifiedPresent;
+    const cycle = {};
+    for (const key of ["number", "timestamp", "type", "phase"]) {
+        if (latest[key] !== null && latest[key] !== undefined && latest[key] !== "")
+            cycle[key] = latest[key];
+    }
+    const pointer = { ...source, cycle_number: latest.number ?? null, field: "verified" };
+    const caveats = verifiedPresent ? [] : ["Latest progress cycle has no non-empty verified evidence."];
+    const evidenceFields = verifiedPresent ? ["verified"] : [];
+    return {
+        status: "available",
+        source_provenance: source,
+        cycle,
+        verified_present: verifiedPresent,
+        non_empty_evidence_present: verifiedPresent,
+        non_empty_evidence_fields: evidenceFields,
+        verified: hasRecordedValue(verified) ? verified : null,
+        verification_summary: hasRecordedValue(verified) ? verified : projectedVerifiedPresent ? { present: true } : null,
+        latest_progress_verification_pointer: pointer,
+        caveats,
+    };
+}
+export function retryState(selected = null, tasks = []) {
+    const task = selected ??
+        tasks.find((candidate) => {
+            const evaluation = candidate.evaluation;
+            return Boolean(evaluation && typeof evaluation === "object" && !Array.isArray(evaluation));
+        }) ??
+        null;
+    const evaluation = task && task.evaluation_state && typeof task.evaluation_state === "object" && !Array.isArray(task.evaluation_state)
+        ? task.evaluation_state
+        : task && task.evaluation && typeof task.evaluation === "object" && !Array.isArray(task.evaluation)
+            ? task.evaluation
+            : null;
+    const source = {
+        source_family: "plan",
+        command: "agentera state plan record-evaluation --id ID --attempt-id ID --verdict {pass,fail}",
+    };
+    if (evaluation) {
+        const attemptCount = Number(evaluation.attempt_count ?? 0);
+        const failureCount = Number(evaluation.failure_count ?? 0);
+        const exhausted = failureCount >= 2;
+        return {
+            status: exhausted ? "exhausted" : "recorded",
+            task: taskRef(task),
+            attempt_count: Number.isInteger(attemptCount) ? attemptCount : null,
+            failure_count: Number.isInteger(failureCount) ? failureCount : null,
+            retry_budget: 2,
+            last_verdict: evaluation.last_verdict ?? null,
+            failure_evidence: evaluation.last_failure_evidence ?? null,
+            provenance: evaluation.provenance ?? null,
+            source_provenance: source,
+            caveats: exhausted ? ["Evaluation retry budget is exhausted; the task is blocked."] : [],
+        };
+    }
+    return {
+        status: "not_recorded",
+        task: task ? taskRef(task) : null,
+        attempt_count: 0,
+        failure_count: 0,
+        retry_budget: 2,
+        last_verdict: null,
+        failure_evidence: null,
+        provenance: null,
+        source_provenance: source,
+        caveats: [],
+    };
+}
+export function evaluatorHandoffOutputRequirementsFromContract() {
+    const contractPath = capabilityInstructionContractPath();
+    if (!isFile(contractPath))
+        return {};
+    try {
+        const contract = loadEvaluatorHandoffContract(contractPath);
+        // cast: contract loaded from parsed capability-instruction-contract.yaml; registry returns Record<string,unknown>
+        return evaluatorHandoffOutputRequirements(contract);
+    }
+    catch {
+        return {};
+    }
+}
+export function evaluatorHandoff(selected, progressVerification, retry, stateCaveats) {
+    const caveats = [...stateCaveats, ...(progressVerification.caveats ?? []), ...(retry.caveats ?? [])];
+    const outputRequirements = evaluatorHandoffOutputRequirementsFromContract();
+    if (selected === null) {
+        caveats.push("No dependency-ready task is selected for evaluator handoff.");
+        return {
+            status: "unavailable",
+            task: null,
+            acceptance_criteria: [],
+            evidence_requirements: [],
+            latest_progress_verification_pointer: progressVerification.latest_progress_verification_pointer ?? null,
+            evaluation_caveats: caveats,
+            output_requirements: outputRequirements,
+        };
+    }
+    const evidenceSummary = selected.evidence_summary && typeof selected.evidence_summary === "object" && !Array.isArray(selected.evidence_summary)
+        ? selected.evidence_summary
+        : null;
+    const evidenceRequirements = (evidenceSummary?.items ?? []);
+    if (evidenceRequirements.length === 0) {
+        caveats.push("Selected task has no explicit evidence requirements recorded in plan state.");
+    }
+    const acceptanceSummary = selected.acceptance_summary && typeof selected.acceptance_summary === "object" && !Array.isArray(selected.acceptance_summary)
+        ? selected.acceptance_summary
+        : null;
+    return {
+        status: "ready",
+        task: taskRef(selected),
+        acceptance_criteria: acceptanceSummary?.items ?? [],
+        evidence_requirements: evidenceRequirements,
+        latest_progress_verification_pointer: progressVerification.latest_progress_verification_pointer ?? null,
+        evaluation_caveats: caveats,
+        output_requirements: outputRequirements,
+    };
+}