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

package/dist/cli/capabilityContext/startup.js

@@ -3,17 +3,31 @@ 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, capabilityContextProfileSummary, docsConventions, fallbackStatePointer, hasRecordedValue, sourceProvenance, taskRef, } from "./shared.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,
-        source_provenance: sourceProvenance("plan", "agentera plan --format json"),
+        diagnostics: asList(plan.diagnostics),
+        invalid_path: plan.invalid_path ?? null,
     };
 }
 export function slimDocsState(docs) {
@@ -26,33 +40,32 @@ export function slimDocsState(docs) {
             version_files: asList(conventions.version_files),
             semver_policy: conventions.semver_policy && typeof conventions.semver_policy === "object" && !Array.isArray(conventions.semver_policy) ? conventions.semver_policy : {},
         },
-        source_provenance: sourceProvenance("docs", "agentera docs --format json", "summary"),
     };
 }
 export function slimProgressState(progress) {
     const latest = progress.latest && typeof progress.latest === "object" && !Array.isArray(progress.latest) ? progress.latest : {};
-    const latestCycle = {};
-    for (const key of ["number", "timestamp", "type", "phase"]) {
-        if (latest[key] !== null && latest[key] !== undefined && latest[key] !== "")
-            latestCycle[key] = latest[key];
+    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(latest.verified),
-        source_provenance: sourceProvenance("progress", "agentera progress --format json"),
+        verified_present: hasRecordedValue(latestRecord.verified),
     };
 }
 export function slimHealthState(health) {
     return {
         exists: Boolean(health.exists),
-        number: health.number ?? null,
+        id: health.id ?? null,
+        artifact: health.artifact ?? "health",
         grade: health.grade ?? null,
         trajectory: health.trajectory ?? null,
         worst: health.worst ?? null,
         degrading: Boolean(health.degrading),
-        source_provenance: sourceProvenance("health", "agentera health --format json"),
     };
 }
 export function slimTodoState(todoItems) {
@@ -61,129 +74,53 @@ export function slimTodoState(todoItems) {
         const severity = String(item.severity ?? "normal");
         severityCounts[severity] = (severityCounts[severity] ?? 0) + 1;
     }
-    return {
-        open_count: todoItems.length,
-        severity_counts: severityCounts,
-        source_provenance: sourceProvenance("todo", "agentera todo --format json"),
-    };
+    return { open_count: todoItems.length, severity_counts: severityCounts, entries: todoItems };
 }
-export function genericSlimStartupContext(capability, context, plan, docs, progress, health, todoItems, profile) {
-    const decisionsPointer = fallbackStatePointer("decisions", "agentera decisions --format json");
+export function genericSlimStartupContext(capability, context, plan, docs, progress, health, todoItems) {
     const docsState = slimDocsState(docs);
-    const profileState = capabilityContextProfileSummary(profile);
-    if (capability === "visionera") {
-        return {
-            vision_startup_context: {
-                vision: fallbackStatePointer("vision", "agentera query vision --format json"),
-                docs_mapping: docsState,
-                progress: slimProgressState(progress),
-                health: slimHealthState(health),
-                todo: slimTodoState(todoItems),
-                decisions: decisionsPointer,
-                design: fallbackStatePointer("design", "agentera query design --format json"),
-                profile: profileState,
-            },
-        };
-    }
-    if (capability === "resonera") {
-        return {
-            deliberation_context: {
-                decisions: decisionsPointer,
-                vision: fallbackStatePointer("vision", "agentera query vision --format json"),
-                objective: fallbackStatePointer("objective", "agentera objective --format json"),
-                todo: slimTodoState(todoItems),
-                docs_mapping: docsState,
-                profile: profileState,
-                protected_write_boundaries: ["vision", "todo", "objective"],
-            },
-        };
+    if (capability === "vision") {
+        return { vision_startup_context: { docs_mapping: docsState, progress: slimProgressState(progress), health: slimHealthState(health), todo: slimTodoState(todoItems) } };
     }
-    if (capability === "inspirera") {
-        return {
-            research_context: {
-                profile: profileState,
-                vision: fallbackStatePointer("vision", "agentera query vision --format json"),
-                write_boundaries: ["todo", "vision"],
-            },
-        };
+    if (capability === "discuss") {
+        return { deliberation_context: { todo: slimTodoState(todoItems), docs_mapping: docsState, protected_write_boundaries: ["vision", "todo", "objective"] } };
     }
-    if (capability === "planera") {
-        return {
-            planning_context: {
-                startup_contract: context.startup_contract ?? null,
-                plan: slimPlanState(plan),
-                docs: docsState,
-                health: slimHealthState(health),
-                todo: slimTodoState(todoItems),
-                progress: slimProgressState(progress),
-                decisions: decisionsPointer,
-                profile: profileState,
-            },
-        };
-    }
-    if (capability === "profilera") {
-        return {
-            profile_context: { profile: profileState, decisions: decisionsPointer, raw_profile_body_emitted: false },
-        };
-    }
-    if (capability === "visualisera") {
-        return {
-            design_context: {
-                design: fallbackStatePointer("design", "agentera query design --format json"),
-                vision: fallbackStatePointer("vision", "agentera query vision --format json"),
-                progress: slimProgressState(progress),
-                todo: slimTodoState(todoItems),
-                docs_mapping: docsState,
-                profile: profileState,
-            },
-        };
+    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, profile, plan, docs, progress, health, todoItems, bespokeContexts) {
+export function slimCapabilityContext(capability, mode, appHome, bundle, plan, docs, progress, health, todoItems, bespokeContexts, cutover = null, todoReconciliation = null) {
     const context = capabilityContext(capability) ?? {
         capability,
-        declared_state_needs: [],
-        declared_write_targets: [],
-        artifact_inventory: { read_needs: [], write_targets: [] },
-        included_state_families: [],
-        missing_state_families: [],
-        cli_fallback: [],
-        raw_artifact_read_policy: "Use the included state families from this prime --context response first. " +
-            "If needed families are missing or CLI state is incomplete, run the CLI fallback commands before raw file access.",
+        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, profile));
+    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;
-    // bespoke contexts are all null for the six non-bespoke capabilities.
     if (bespokeContexts) {
         for (const [name, value] of Object.entries(bespokeContexts)) {
             if (value !== null && value !== undefined)
                 contextPayload[name] = slimBespokeContext(name, value);
         }
     }
-    const prose = CAPABILITY_INSTRUCTIONS[capability] ?? null;
     return {
         schemaVersion: "agentera.capabilityContext.v1",
         capability,
         mode,
         app: capabilityContextAppSummary(appHome, bundle),
-        profile: capabilityContextProfileSummary(profile),
-        state: {
-            declared_read_needs: context.declared_state_needs ?? [],
-            declared_write_targets: context.declared_write_targets ?? [],
-            artifact_inventory: context.artifact_inventory ?? { read_needs: [], write_targets: [] },
-            included: context.included_state_families ?? [],
-            missing: context.missing_state_families ?? [],
-            fallback_commands: context.cli_fallback ?? [],
-            schema_error: context.schema_error ?? null,
-        },
-        context: contextPayload,
-        prose: prose ?? "",
-        raw_artifact_read_policy: context.raw_artifact_read_policy ?? null,
+        startup: startupAggregation(context, health, cutover, todoReconciliation),
+        context: boundStartupValue(contextPayload),
+        instructions: CAPABILITY_INSTRUCTIONS[capability] ?? "",
     };
 }
 export function orientationAppHome(bundle) {
@@ -195,14 +132,19 @@ export function orientationAppHome(bundle) {
         user_data_root: bundle.userDataRoot,
     };
 }
-export function buildPrimeCapabilityContextPayload(state, capabilityName, command = "prime") {
-    const bundlePublic = publicDoctorStatus(state.bundle);
-    const appHome = orientationAppHome(state.bundle);
-    const bespoke = bespokeCapabilityContexts(capabilityName, state);
+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,
-        status: "ok",
-        capability_context: slimCapabilityContext(capabilityName, state.mode, appHome, bundlePublic, state.profile_dict, state.plan, state.docs, state.progress, state.health, state.todo_items, bespoke),
+        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),
     };
 }
-//# sourceMappingURL=startup.js.map

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 === "required" || cutover?.status === "invalid_lifecycle";
+    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

@@ -1,43 +1,56 @@
-export const CAPABILITY_NAMES = [
-    "hej", "visionera", "resonera", "inspirera", "planera", "realisera",
-    "optimera", "inspektera", "dokumentera", "profilera", "visualisera", "orkestrera",
-];
-export const BESPOKE_CONTEXT_CAPABILITIES = new Set([]);
+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: "agentera plan --format json",
-    docs: "agentera docs --format json",
-    progress: "agentera progress --format json",
-    health: "agentera health --format json",
-    todo: "agentera todo --format json",
-    decisions: "agentera decisions --format json",
-    changelog: "agentera query changelog --format json",
-    objective: "agentera objective --format json",
-    experiments: "agentera experiments --format json",
+    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 PLANERA_STARTUP_CONTRACT_VERSION = "agentera.planeraStartup.v1";
-export const PLANERA_PLANNING_LEVELS = ["skip", "light", "full"];
-export const PLANERA_STEP_VERBS = ["orient", "specify", "review", "audit", "write", "handoff"];
-export const PLANERA_INSTRUCTIONS_AUTHORITY_EXCEPTIONS = [
-    "editing Planera behavior or instructions",
+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 PLANERA_RAW_PLAN_ACCESS_ALLOWED_FOR = [
+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 PLANERA_COMPLETED_PLAN_ARCHIVE_CONFIRMATION = {
-    direct_planera_invocation: "Archiving an already completed existing plan before writing its replacement is implicit " +
-        "in the direct Planera invocation and does not require a separate pre-write confirmation.",
+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.",
 };
-//# sourceMappingURL=types.js.map

package/dist/cli/capabilityContext.js

@@ -1,2 +1 @@
-export { CAPABILITY_NAMES, BESPOKE_CONTEXT_CAPABILITIES, validatePrimeCapability, buildPrimeCapabilityContextPayload } from "./capabilityContext/index.js";
-//# sourceMappingURL=capabilityContext.js.map
+export { CAPABILITY_NAMES, validatePrimeCapability, buildPrimeCapabilityContextPayload } from "./capabilityContext/index.js";

package/dist/cli/commands/appHome.js

@@ -0,0 +1,22 @@
+import os from "node:os";
+import { formatResolvedAppHome } from "../../state/installRoot.js";
+import { expanduser } from "../../core/paths.js";
+export function cmdAppHome(args, io = {}) {
+    const out = io.out ?? ((t) => process.stdout.write(t));
+    const resolvedHome = args.home ? expanduser(args.home) : os.homedir();
+    let env = process.env;
+    if (args.home) {
+        env = { ...process.env, HOME: resolvedHome };
+        delete env.XDG_DATA_HOME;
+        delete env.APPDATA;
+        delete env.AGENTERA_HOME;
+        delete env.AGENTERA_DEFAULT_INSTALL_ROOT;
+    }
+    const output = formatResolvedAppHome(args.installRoot, {
+        env,
+        home: resolvedHome,
+        format: args.format,
+    });
+    out(output + "\n");
+    return 0;
+}

package/dist/cli/commands/capability.js

@@ -1,9 +1,10 @@
 import { emitStructured } from "../structured.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
 export const CAPABILITY_ROUTING_NAMES = [
-    "visionera", "resonera", "inspirera", "planera", "realisera",
-    "optimera", "inspektera", "dokumentera", "profilera", "visualisera", "orkestrera",
+    "vision", "discuss", "research", "plan", "build",
+    "optimize", "audit", "document", "profile", "design", "orchestrate",
 ];
-const PRIME_CAPABILITY_CONTEXT_COMMAND = "agentera prime --context {capability} --format json";
+const PRIME_CAPABILITY_CONTEXT_COMMAND = preCutoverCommand("prime --context {capability} --format json");
 export function cmdCapability(capability, args, io) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     const instructionsPath = `packages/cli/src/capabilities/${capability}/instructions.ts`;
@@ -34,4 +35,3 @@ export function cmdCapability(capability, args, io) {
     }
     return 0;
 }
-//# sourceMappingURL=capability.js.map