agentera 3.0.0-dev.5 → 3.0.0-dev.51

package/dist/cli/capabilityContext/startup.js

@@ -0,0 +1,150 @@
+import { publicDoctorStatus } from "../../upgrade/doctor.js";
+import { CAPABILITY_INSTRUCTIONS } from "../../capabilities/index.js";
+import { asList } from "../stateQuery.js";
+import { capabilityContext } from "./contract.js";
+import { bespokeCapabilityContexts, slimBespokeContext } from "./bespoke.js";
+import { capabilityContextAppSummary, docsConventions, hasRecordedValue, taskRef } from "./shared.js";
+import { boundStartupValue } from "../../state/startupProjection.js";
+import { startupAggregation } from "./startupAggregation.js";
+export function slimPlanState(plan) {
+    const firstPending = plan.first_pending;
+    const tasks = asList(plan.tasks)
+        .filter((task) => Boolean(task) && typeof task === "object" && !Array.isArray(task))
+        .map(taskRef);
+    return {
+        exists: Boolean(plan.exists),
+        active: Boolean(plan.active),
+        complete_plan: Boolean(plan.complete_plan),
+        id: plan.id ?? null,
+        artifact: plan.artifact ?? "plan",
+        status: plan.status ?? null,
+        title: plan.title ?? null,
+        complete: plan.complete ?? null,
+        superseded: plan.superseded ?? null,
+        total: plan.total ?? null,
+        task_status_counts: plan.task_status_counts ?? {},
+        task_omission: plan.task_omission ?? { omitted: false },
+        tasks,
+        first_pending: firstPending && typeof firstPending === "object" && !Array.isArray(firstPending) ? taskRef(firstPending) : null,
+        diagnostics: asList(plan.diagnostics),
+        invalid_path: plan.invalid_path ?? null,
+    };
+}
+export function slimDocsState(docs) {
+    const conventions = docsConventions(docs);
+    return {
+        exists: Boolean(docs.exists),
+        status: docs.status ?? null,
+        mapping_entries: docs.mapping_entries ?? asList(docs.mapping).length,
+        version_policy: {
+            version_files: asList(conventions.version_files),
+            semver_policy: conventions.semver_policy && typeof conventions.semver_policy === "object" && !Array.isArray(conventions.semver_policy) ? conventions.semver_policy : {},
+        },
+    };
+}
+export function slimProgressState(progress) {
+    const latest = progress.latest && typeof progress.latest === "object" && !Array.isArray(progress.latest) ? progress.latest : {};
+    const latestRecord = latest.record && typeof latest.record === "object" && !Array.isArray(latest.record) ? latest.record : latest;
+    const latestCycle = { id: latest.id ?? null, artifact: latest.artifact ?? "progress" };
+    for (const key of ["timestamp", "type", "phase"]) {
+        if (latestRecord[key] !== null && latestRecord[key] !== undefined && latestRecord[key] !== "")
+            latestCycle[key] = latestRecord[key];
+    }
+    return {
+        exists: Boolean(progress.exists),
+        status: progress.status ?? null,
+        latest_cycle: latestCycle,
+        verified_present: hasRecordedValue(latestRecord.verified),
+    };
+}
+export function slimHealthState(health) {
+    return {
+        exists: Boolean(health.exists),
+        id: health.id ?? null,
+        artifact: health.artifact ?? "health",
+        grade: health.grade ?? null,
+        trajectory: health.trajectory ?? null,
+        worst: health.worst ?? null,
+        degrading: Boolean(health.degrading),
+    };
+}
+export function slimTodoState(todoItems) {
+    const severityCounts = {};
+    for (const item of todoItems) {
+        const severity = String(item.severity ?? "normal");
+        severityCounts[severity] = (severityCounts[severity] ?? 0) + 1;
+    }
+    return { open_count: todoItems.length, severity_counts: severityCounts, entries: todoItems };
+}
+export function genericSlimStartupContext(capability, context, plan, docs, progress, health, todoItems) {
+    const docsState = slimDocsState(docs);
+    if (capability === "vision") {
+        return { vision_startup_context: { docs_mapping: docsState, progress: slimProgressState(progress), health: slimHealthState(health), todo: slimTodoState(todoItems) } };
+    }
+    if (capability === "discuss") {
+        return { deliberation_context: { todo: slimTodoState(todoItems), docs_mapping: docsState, protected_write_boundaries: ["vision", "todo", "objective"] } };
+    }
+    if (capability === "research")
+        return { research_context: { write_boundaries: ["todo", "vision"] } };
+    if (capability === "plan") {
+        return { planning_context: { startup_contract: context.startup_contract ?? null, plan: slimPlanState(plan), docs: docsState, health: slimHealthState(health), todo: slimTodoState(todoItems), progress: slimProgressState(progress) } };
+    }
+    if (capability === "profile")
+        return { profile_context: { raw_profile_body_emitted: false } };
+    if (capability === "design")
+        return { design_context: { progress: slimProgressState(progress), todo: slimTodoState(todoItems), docs_mapping: docsState } };
+    return {};
+}
+export function slimCapabilityContext(capability, mode, appHome, bundle, plan, docs, progress, health, todoItems, bespokeContexts, cutover = null, todoReconciliation = null) {
+    const context = capabilityContext(capability) ?? {
+        capability,
+        availability: [],
+        schema_error: `No capability context found for ${capability}.`,
+    };
+    const contextPayload = { capability, schema_error: context.schema_error ?? null };
+    Object.assign(contextPayload, genericSlimStartupContext(capability, context, plan, docs, progress, health, todoItems));
+    contextPayload.plan = slimPlanState(plan);
+    const firstRead = context.first_invocation_read;
+    if (firstRead !== null && firstRead !== undefined)
+        contextPayload.first_invocation_read = firstRead;
+    if (bespokeContexts) {
+        for (const [name, value] of Object.entries(bespokeContexts)) {
+            if (value !== null && value !== undefined)
+                contextPayload[name] = slimBespokeContext(name, value);
+        }
+    }
+    return {
+        schemaVersion: "agentera.capabilityContext.v1",
+        capability,
+        mode,
+        app: capabilityContextAppSummary(appHome, bundle),
+        startup: startupAggregation(context, health, cutover, todoReconciliation),
+        context: boundStartupValue(contextPayload),
+        instructions: CAPABILITY_INSTRUCTIONS[capability] ?? "",
+    };
+}
+export function orientationAppHome(bundle) {
+    return {
+        status: bundle.status,
+        home: bundle.appHome,
+        source: bundle.appHomeSource,
+        managed_app_root: bundle.managedAppRoot,
+        user_data_root: bundle.userDataRoot,
+    };
+}
+export function buildPrimeCapabilityContextPayload(state, capabilityName, command = "prime", buildRequest = null) {
+    const stateDict = state;
+    const bundlePublic = publicDoctorStatus(state.app);
+    const appHome = orientationAppHome(stateDict.app);
+    const bespoke = bespokeCapabilityContexts(capabilityName, stateDict, buildRequest);
+    const contract = capabilityContext(capabilityName) ?? {};
+    const cutover = stateDict.state_cutover;
+    const todoReconciliation = stateDict.todo_reconciliation ?? null;
+    const startup = startupAggregation(contract, stateDict.health, cutover, todoReconciliation);
+    return {
+        command,
+        outcome: startup.outcome,
+        shared_skill: stateDict.shared_skill,
+        capability_context: slimCapabilityContext(capabilityName, state.mode, appHome, bundlePublic, stateDict.plan, stateDict.docs, stateDict.progress, stateDict.health, state.todo_items, bespoke, cutover, todoReconciliation),
+    };
+}

package/dist/cli/capabilityContext/startupAggregation.js

@@ -0,0 +1,68 @@
+import { preCutoverCommand } from "../preCutoverCommand.js";
+export const STARTUP_INCLUDED_FAMILIES = new Set([
+    "plan",
+    "docs",
+    "progress",
+    "health",
+    "todo",
+    "objective",
+]);
+const DETAIL_COMMANDS = {
+    plan: preCutoverCommand("state plan list --format json"),
+    docs: preCutoverCommand("state docs list --format json"),
+    progress: preCutoverCommand("state progress list --format json"),
+    health: preCutoverCommand("state health list --format json"),
+    todo: preCutoverCommand("state todo list --format json"),
+    decisions: preCutoverCommand("state decisions list --format json"),
+    changelog: preCutoverCommand("state query changelog --format json"),
+    objective: preCutoverCommand("state objective list --format json"),
+    experiments: preCutoverCommand("state experiments list --objective OBJECTIVE_ID --format json"),
+    vision: preCutoverCommand("state query vision --format json"),
+    design: preCutoverCommand("state query design --format json"),
+    profile: preCutoverCommand("report profile-grounding --format json"),
+};
+function detailCommand(family) {
+    return DETAIL_COMMANDS[family] ?? preCutoverCommand("schema --format json");
+}
+/**
+ * The only per-family startup inventory. `included` means the bounded capsule
+ * carries a summary for that family; `deferred` means callers can discover
+ * detail through the exact read command without receiving a writer payload.
+ */
+export function startupAvailabilityProjection(families) {
+    return [...new Set(families)].map((family) => ({
+        family,
+        availability: STARTUP_INCLUDED_FAMILIES.has(family) ? "included" : "deferred",
+        detail_command: detailCommand(family),
+    }));
+}
+export function deferredStartupFamilies(contract) {
+    const availability = Array.isArray(contract.availability) ? contract.availability : [];
+    return availability.flatMap((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return [];
+        const row = entry;
+        return row.availability === "deferred" && typeof row.family === "string" ? [row.family] : [];
+    });
+}
+/**
+ * Prime aggregates read availability. Mutation grammar remains discoverable
+ * only through `agentera schema`, never through a startup payload.
+ */
+export function startupAggregation(contract, health, cutover = null, todoReconciliation = null) {
+    const cutoverRequired = cutover?.status !== undefined && cutover.status !== "complete";
+    const reconciliationRequired = todoReconciliation?.status === "action_required";
+    const blocked = cutoverRequired || reconciliationRequired || (typeof contract.schema_error === "string" && contract.schema_error.length > 0);
+    const degraded = health.startup_outcome === "degraded";
+    const outcome = blocked ? "blocked" : degraded ? "degraded" : "ok";
+    return {
+        schemaVersion: "agentera.primeStartup.v1",
+        outcome,
+        state_cutover: cutover ?? { status: "complete", project_state: "v3", recovery_command: null },
+        ...(reconciliationRequired ? { todo_reconciliation: todoReconciliation } : {}),
+        availability: Array.isArray(contract.availability) ? contract.availability : [],
+        detail_discovery: { schema: preCutoverCommand("schema --format json") },
+        raw_artifact_reads_required: false,
+        raw_artifact_read_policy: "Use included bounded state first. For deferred detail, run that family's detail_command; raw reads are only for a named corruption or CLI-defect diagnostic.",
+    };
+}

package/dist/cli/capabilityContext/types.js

@@ -0,0 +1,56 @@
+import { CAPABILITY_INSTRUCTIONS } from "../../capabilities/index.js";
+import { entityListFamily } from "../../state/entityRetrievalHelp.js";
+import { preCutoverCommand, preCutoverCommandFromBare } from "../preCutoverCommand.js";
+export const CAPABILITY_NAMES = Object.keys(CAPABILITY_INSTRUCTIONS);
+function canonicalListCommand(key) {
+    const family = entityListFamily(key);
+    return preCutoverCommand(`state ${family.commandTokens.join(" ")} list --format json`);
+}
+export const STATE_FAMILY_FALLBACK_COMMANDS = {
+    plan: canonicalListCommand("plans"),
+    docs: canonicalListCommand("docs"),
+    progress: canonicalListCommand("progress"),
+    health: canonicalListCommand("health"),
+    todo: canonicalListCommand("todo"),
+    decisions: canonicalListCommand("decisions"),
+    changelog: preCutoverCommand("state query changelog --format json"),
+    objective: canonicalListCommand("objective"),
+    experiments: preCutoverCommandFromBare(entityListFamily("experiments").syntax),
+};
+export const STATE_FAMILY_LIST_COMMANDS = {
+    progress: canonicalListCommand("progress"),
+    decisions: canonicalListCommand("decisions"),
+    health: canonicalListCommand("health"),
+};
+export const STATE_FAMILY_GET_COMMANDS = {
+    progress: entityListFamily("progress").get,
+    decisions: entityListFamily("decisions").get,
+    health: entityListFamily("health").get,
+};
+export const STARTUP_ENVELOPE_STATE_FAMILIES = new Set([
+    "plan", "docs", "progress", "health", "todo", "objective", "benchmark_context",
+]);
+export const PLAN_STARTUP_CONTRACT_VERSION = "agentera.planeraStartup.v1";
+export const PLAN_PLANNING_LEVELS = ["skip", "light", "full"];
+export const PLAN_STEP_VERBS = ["orient", "specify", "review", "audit", "write", "handoff"];
+export const PLAN_TASK_COHERENCE_RULE = "Keep full-plan tasks within a coherent lifecycle boundary; split only at real lifecycle or coherence boundaries.";
+export const PLAN_INSTRUCTIONS_AUTHORITY_EXCEPTIONS = [
+    "editing Plan behavior or instructions",
+    "resolving contradiction or ambiguity in compact context",
+    "validating detailed behavior not covered by compact context",
+    "investigating benchmark or read-trigger evidence",
+];
+export const PLAN_RAW_PLAN_ACCESS_ALLOWED_FOR = [
+    "writing a new plan",
+    "archiving a completed plan",
+    "artifact validation",
+    "corruption diagnostics",
+    "unavailable or incomplete CLI state after CLI fallbacks",
+];
+export const PLAN_COMPLETED_PLAN_ARCHIVE_CONFIRMATION = {
+    direct_plan_invocation: "Archiving an already completed existing plan before writing its replacement is implicit " +
+        "in the direct Plan invocation and does not require a separate pre-write confirmation.",
+    human_initiated_plan_write: "Plan approval is still required before writing a human-initiated replacement plan.",
+    active_or_incomplete_plan: "Replacing, discarding, or archiving an active or incomplete plan is not implicit; " +
+        "ask for explicit confirmation before the write.",
+};