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

package/dist/state/installRoot.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { expanduser, isFile, pathExists, resolvePath } from "../core/paths.js";
+import { loadTomlFile } from "../core/toml.js";
 /**
  * Read-only Agentera install-root classification. Faithful TypeScript port of
  * `scripts/install_root.py`. Owns install-root identity and diagnostics without
@@ -75,18 +76,12 @@ export function resolveCandidate(explicitRoot, opts) {
 }
 export function defaultAppHome(env, home, platform = process.platform) {
     if (platform === "darwin") {
-        return path.join(expanduser(home), "Library", "Application Support", "agentera");
+        return macosDefaultAppHome(home);
     }
     if (platform === "win32") {
-        const appdata = env.APPDATA;
-        const base = appdata
-            ? expanduser(appdata)
-            : path.join(expanduser(home), "AppData", "Roaming");
-        return path.join(base, "agentera");
+        return windowsDefaultAppHome(env, home);
     }
-    const xdg = env.XDG_DATA_HOME;
-    const base = xdg ? expanduser(xdg) : path.join(expanduser(home), ".local", "share");
-    return path.join(base, "agentera");
+    return linuxDefaultAppHome(env, home);
 }
 function linuxDefaultAppHome(env, home) {
     const xdg = env.XDG_DATA_HOME;
@@ -148,11 +143,17 @@ function managedFresh(root, source, setupMissing, bundleMissing, expected, curre
         },
     }, { expectedVersion: expected, currentVersion: current });
 }
+function managedStaleDiagnosticMessage(reason) {
+    if (reason === "version_mismatch") {
+        return "Agentera app files are valid but need an update to the expected version";
+    }
+    return "Agentera app files need repair";
+}
 function managedStale(root, source, expected, current, missingEvidence, reason, evidence) {
     return classification(root, source, "managed_stale", "preview_refresh", "managed", "stale", missingEvidence, {
         code: "install_root.managed_stale",
         severity: "warning",
-        message: "Agentera app files need repair",
+        message: managedStaleDiagnosticMessage(reason),
         evidence: { path: root, source: sourceLabel(source), reason, ...evidence },
     }, { expectedVersion: expected, currentVersion: current });
 }
@@ -162,30 +163,37 @@ function missingEntries(root, entries) {
 function readBundleMarker(root) {
     const marker = path.join(root, BUNDLE_MARKER);
     if (!isFile(marker)) {
-        return null;
+        return { kind: "absent" };
     }
     try {
         const data = JSON.parse(fs.readFileSync(marker, "utf8"));
-        return data && typeof data === "object" && !Array.isArray(data)
-            ? data
-            : null;
+        if (data && typeof data === "object" && !Array.isArray(data)) {
+            return { kind: "valid", data: data };
+        }
+        return { kind: "corrupt" };
     }
     catch {
-        return null;
+        return { kind: "corrupt" };
     }
 }
-function missingScriptCommands(script, commands) {
-    if (!isFile(script)) {
-        return [...commands];
+const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+function readPyprojectVersion(root) {
+    const pyprojectPath = path.join(root, "pyproject.toml");
+    if (!isFile(pyprojectPath)) {
+        return null;
     }
-    let text;
     try {
-        text = fs.readFileSync(script, "utf8");
+        const data = loadTomlFile(pyprojectPath);
+        const project = data.project;
+        if (project && typeof project === "object" && !Array.isArray(project)) {
+            const version = project.version;
+            return typeof version === "string" && version ? version : null;
+        }
     }
     catch {
-        return [...commands];
+        // fall through
     }
-    return commands.filter((command) => !text.includes(command));
+    return null;
 }
 export function classifyResolvedRoot(rootInput, opts) {
     const root = resolvePath(rootInput);
@@ -221,12 +229,28 @@ export function classifyResolvedRoot(rootInput, opts) {
     const hasSetupEvidence = setupMissing.length === 0;
     const hasBundleEvidence = bundleMissing.length === 0;
     const presentEvidence = MANAGED_EVIDENCE.filter((entry) => pathExists(path.join(root, entry)));
-    const marker = readBundleMarker(root);
-    const current = marker?.version ?? null;
+    const markerRead = readBundleMarker(root);
+    const marker = markerRead.kind === "valid" ? markerRead.data : null;
+    let current = marker?.version ?? null;
+    // Fall back to pyproject.toml when the marker version is not a valid semver
+    // (e.g. stale "v1" or placeholder "current" from v2-era installs).
+    if (current !== null && !SEMVER_PREFIX.test(current)) {
+        const pyprojectVersion = readPyprojectVersion(root);
+        if (pyprojectVersion !== null) {
+            current = pyprojectVersion;
+        }
+    }
     if (hasSetupEvidence && !pathExists(path.join(root, BUNDLE_MARKER))) {
         return managedFresh(root, source, setupMissing, bundleMissing, expected, current);
     }
     if (hasBundleEvidence) {
+        if (markerRead.kind === "corrupt") {
+            return managedStale(root, source, expected, current, ["a valid bundle marker file"], "corrupt_marker", {
+                expectedVersion: expected,
+                currentVersion: current,
+                markerPath: path.join(root, BUNDLE_MARKER),
+            });
+        }
         if (expected !== null && current !== expected) {
             return managedStale(root, source, expected, current, ["current bundle marker/version or required CLI command evidence"], "version_mismatch", {
                 expectedVersion: expected,
@@ -276,4 +300,19 @@ export function classifyInstallRoot(explicitRoot, opts) {
 export function formatDiagnostic(c) {
     return `${c.diagnostic.severity}: ${c.diagnostic.message} (${c.path})`;
 }
-//# sourceMappingURL=installRoot.js.map
+/** Resolved app-home path for agent/bootstrap callers (port of install_root.py). */
+export function formatResolvedAppHome(explicitRoot, opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? expanduser("~");
+    const platform = opts.platform ?? process.platform;
+    const [resolvedPath, source] = resolveCandidate(explicitRoot ?? null, { env, home, platform });
+    if ((opts.format ?? "text") === "json") {
+        return JSON.stringify({
+            path: resolvedPath,
+            source,
+            sourceLabel: sourceLabel(source),
+            platform,
+        });
+    }
+    return resolvedPath;
+}

package/dist/state/legacyEntityCutoverEvidence.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { loadYamlMapping } from "../core/yaml.js";
+import { validateRealProjectRoot } from "./projectRoot.js";
+import { readProjectFileSnapshot } from "./safeProjectFile.js";
+function hash(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function read(project, relative) {
+    const observed = readProjectFileSnapshot(validateRealProjectRoot(project), relative);
+    if (observed.kind !== "file")
+        throw new Error(`historical entity cutover evidence '${relative}' is missing or unsafe`);
+    return observed.bytes;
+}
+function safeTarget(value) {
+    return value.startsWith(".agentera/entities/")
+        && !path.isAbsolute(value)
+        && value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+/** Minimal read-only compatibility required by public state validation. */
+export function loadLegacyEntityCutoverTargets(projectRoot, markerBytes) {
+    const project = validateRealProjectRoot(projectRoot).path;
+    const marker = loadYamlMapping(markerBytes.toString("utf8"));
+    const id = marker.migration_id;
+    if (typeof id !== "string" || !/^[a-f0-9]{20}$/.test(id))
+        throw new Error("entity marker has no valid historical migration binding");
+    const root = `.agentera/migrations/entities/${id}`;
+    const journalBytes = read(project, `${root}/journal.yaml`);
+    const manifestBytes = read(project, `${root}/manifest.yaml`);
+    const journal = loadYamlMapping(journalBytes.toString("utf8"));
+    const manifest = loadYamlMapping(manifestBytes.toString("utf8"));
+    if (journal.schemaVersion !== "agentera.entityMigrationJournal.v1"
+        || journal.migration_id !== id
+        || journal.phase !== "cutover_complete"
+        || journal.manifest_sha256 !== hash(manifestBytes)
+        || manifest.schemaVersion !== "agentera.entityMigrationManifest.v1"
+        || manifest.migration_id !== id
+        || journal.source_fingerprint !== marker.source_fingerprint
+        || journal.preview_digest !== marker.preview_digest
+        || manifest.source_fingerprint !== marker.source_fingerprint
+        || manifest.preview_digest !== marker.preview_digest) {
+        throw new Error(`historical entity cutover evidence '${id}' does not match its marker`);
+    }
+    const receipts = mapping(manifest.receipts) ? manifest.receipts : {};
+    const markerReceipt = mapping(receipts[".agentera/state-mode.yaml"]) ? receipts[".agentera/state-mode.yaml"] : null;
+    if (!markerReceipt || markerReceipt.sha256 !== hash(markerBytes))
+        throw new Error(`historical entity cutover marker '${id}' diverges from its manifest`);
+    if (!Array.isArray(manifest.entries))
+        throw new Error(`historical entity cutover manifest '${id}' has no target inventory`);
+    const targets = manifest.entries.map((value) => {
+        const entry = mapping(value) ? value : {};
+        const target = mapping(entry.proposed_target) ? entry.proposed_target : {};
+        if (typeof target.path !== "string" || !safeTarget(target.path) || typeof target.id !== "string" || typeof entry.artifact !== "string" || typeof entry.target_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(entry.target_sha256)) {
+            throw new Error(`historical entity cutover manifest '${id}' has an invalid target`);
+        }
+        return { path: target.path, sha256: entry.target_sha256, id: target.id, artifact: entry.artifact };
+    });
+    if (new Set(targets.map(({ path: target }) => target)).size !== targets.length) {
+        throw new Error(`historical entity cutover manifest '${id}' target inventory is duplicated`);
+    }
+    return targets;
+}

package/dist/state/legacyIdentity.js

@@ -0,0 +1,47 @@
+function positiveNumber(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+        return value;
+    if (typeof value === "string" && /^[1-9][0-9]*$/.test(value)) {
+        const parsed = Number(value);
+        return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+    }
+    return null;
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * A shorthand is an identity only when it is the leading token of a decision
+ * summary. References later in the prose are evidence, not identity.
+ */
+const LEADING_DECISION_SHORTHAND = /^D([1-9][0-9]*)(?=$|[\s:([,.;])/;
+const LEADING_DECISION_COMPOUND = /^D[1-9][0-9]*\s*\+\s*D[1-9][0-9]*/;
+export function legacyIdentity(value, artifactId, entryNumberField) {
+    const object = mapping(value);
+    if (object) {
+        const explicit = positiveNumber(object[entryNumberField]);
+        if (explicit !== null)
+            return { number: explicit, kind: "canonical_number" };
+        if (typeof object.summary === "string")
+            return legacyIdentity(object.summary, artifactId, entryNumberField);
+        return { number: null, kind: "unaddressable" };
+    }
+    if (typeof value !== "string")
+        return { number: null, kind: "unaddressable" };
+    const text = value.trim();
+    if (artifactId === "decisions") {
+        if (LEADING_DECISION_COMPOUND.test(text))
+            return { number: null, kind: "ambiguous" };
+        const shorthand = LEADING_DECISION_SHORTHAND.exec(text);
+        if (shorthand)
+            return { number: positiveNumber(shorthand[1]), kind: "explicit_decision_shorthand" };
+    }
+    const label = artifactId === "progress" ? "Cycle" : artifactId === "decisions" ? "Decision" : "Audit";
+    const match = new RegExp(`^${label}\\s+([1-9][0-9]*)\\b`).exec(text);
+    return match ? { number: positiveNumber(match[1]), kind: "canonical_number" } : { number: null, kind: "unaddressable" };
+}
+export function legacyEntryNumber(value, artifactId, entryNumberField) {
+    return legacyIdentity(value, artifactId, entryNumberField).number;
+}

package/dist/state/legacySummaryRecord.js

@@ -0,0 +1,6 @@
+/** Normalize exactly the legacy summary row shapes accepted by migration preview. */
+export function legacySummaryRecord(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value))
+        return value;
+    return typeof value === "string" ? { summary: value } : null;
+}

package/dist/state/listAccounting.js

@@ -0,0 +1,54 @@
+export function physicalCounts(candidates) {
+    let physical = 0;
+    let addressable = 0;
+    let unaddressable = 0;
+    let ambiguous = 0;
+    let mirrored = 0;
+    let duplicate = 0;
+    let conflict = 0;
+    for (const candidate of candidates) {
+        physical += candidate.rows.length;
+        for (const row of candidate.rows) {
+            if (row.entryNumber !== null && row.identity !== "ambiguous")
+                addressable += 1;
+            else if (row.identity === "ambiguous")
+                ambiguous += 1;
+            else
+                unaddressable += 1;
+        }
+        const currentRows = candidate.rows.filter((row) => row.source === "current_projection");
+        const archiveRows = candidate.rows.filter((row) => row.source === "archive" && row.origin === "numbered_archive");
+        const comparable = candidate.rows.filter((row) => row.representation === "full");
+        const exactMirror = archiveRows.length > 0 && currentRows.length > 0 && new Set(comparable.map((row) => row.projectionHash)).size <= 1;
+        if (exactMirror)
+            mirrored += 1;
+        if (candidate.classification === "duplicate")
+            duplicate += Math.max(0, candidate.rows.length - 1 - (exactMirror ? 1 : 0));
+        if (candidate.classification === "conflict")
+            conflict += Math.max(0, candidate.rows.length - 1);
+    }
+    return {
+        physical,
+        addressable,
+        addressable_ids: candidates.filter((candidate) => candidate.stableId !== null).length,
+        unaddressable,
+        ambiguous,
+        canonical: Math.max(0, addressable - mirrored - duplicate - conflict),
+        mirrored,
+        duplicate,
+        conflict,
+        logical: candidates.length,
+    };
+}
+export function provenanceCounts(entries) {
+    const counts = { archive: 0, legacy_full: 0, legacy_summary: 0, unavailable: 0 };
+    for (const entry of entries) {
+        const source = String(entry.source ?? "unavailable");
+        if (source in counts)
+            counts[source] = Number(counts[source]) + 1;
+        else
+            counts.unavailable = Number(counts.unavailable) + 1;
+    }
+    counts.candidate_count = entries.length;
+    return counts;
+}

package/dist/state/listClassification.js

@@ -0,0 +1,17 @@
+/** The one row-group classification used by state list and startup projections. */
+export function classifyStateRows(rows) {
+    if (rows.some((row) => row.rejection))
+        return "corrupt";
+    if (rows.some((row) => row.identity === "ambiguous"))
+        return "ambiguous";
+    const comparable = rows.filter((row) => row.representation === "full");
+    if (new Set(comparable.map((row) => row.projectionHash)).size > 1)
+        return "conflict";
+    const currentRows = rows.filter((row) => row.source === "current_projection");
+    const archiveRows = rows.filter((row) => row.source === "archive" && row.origin === "numbered_archive");
+    if (archiveRows.length > 0 && currentRows.length > 0 && currentRows.length === 1)
+        return "mirrored";
+    if (rows.length > 1)
+        return "duplicate";
+    return "canonical";
+}

package/dist/state/listCursor.js

@@ -0,0 +1,42 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+function cursorKey(projectRoot, authorityPath) {
+    return createHash("sha256")
+        .update(path.resolve(projectRoot))
+        .update("\0")
+        .update(fs.readFileSync(authorityPath))
+        .digest();
+}
+function decodeCanonicalSegment(segment) {
+    if (!BASE64URL.test(segment))
+        throw new Error("noncanonical base64url");
+    const bytes = Buffer.from(segment, "base64url");
+    if (bytes.toString("base64url") !== segment)
+        throw new Error("noncanonical base64url");
+    return bytes;
+}
+export function encodeListCursor(payload, projectRoot, authorityPath) {
+    const bytes = Buffer.from(canonicalRecordJson(payload), "utf8");
+    const signature = createHmac("sha256", cursorKey(projectRoot, authorityPath)).update(bytes).digest();
+    return `${bytes.toString("base64url")}.${signature.toString("base64url")}`;
+}
+export function decodeListCursor(token, projectRoot, authorityPath) {
+    const parts = token.split(".");
+    if (parts.length !== 2)
+        throw new Error("malformed cursor");
+    const bytes = decodeCanonicalSegment(parts[0]);
+    const supplied = decodeCanonicalSegment(parts[1]);
+    const expected = createHmac("sha256", cursorKey(projectRoot, authorityPath)).update(bytes).digest();
+    if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected))
+        throw new Error("invalid cursor signature");
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid cursor payload");
+    return value;
+}
+export function projectedListSnapshot(projection) {
+    return createHash("sha256").update(canonicalRecordJson(projection), "utf8").digest("hex");
+}