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

package/dist/upgrade/installedHooksRetirement.js

@@ -0,0 +1,196 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isFile, pathExists, resolvePath } from "../core/paths.js";
+import { doctorRoots } from "./appModel.js";
+import { hasBundleRootEvidence } from "./bundleEvidence.js";
+import { bindMigrationResource, removeBoundMigrationResource, verifyBoundMigrationResource, } from "./migrationPublication.js";
+export const INSTALLED_HOOKS_SURFACE_LABEL = "hooks/";
+export const RETIRE_INSTALLED_HOOKS_ACTION = "retire-installed-hooks";
+const V2_HOOK_INVOCATION_PATTERNS = [
+    /\buv run\b[^"'\n]*hooks\/[^"'\n]*\.py/,
+    /\$\{AGENTERA_HOME\}\/hooks\/[^"'\n]*\.py/,
+    /\$\{AGENTERA_HOME\}\/app\/hooks\/[^"'\n]*\.py/,
+    /\$\{PLUGIN_ROOT\}\/hooks\/[^"'\n]*\.py/,
+];
+const SKIP_HOOK_SCAN_PARTS = new Set([".agentera", "sessions", "benchmarks", "intermediate", "backup"]);
+const V2_INSTALLED_HOOK_FILES = new Set([
+    "validate_artifact.py",
+    "cursor_session_start.py",
+    "cursor_pre_tool_use.py",
+    "cursor_session_stop.py",
+    "session_start.py",
+    "session_stop.py",
+    "codex-hooks.json",
+]);
+function hooksDirHasPythonFiles(hooksDir) {
+    if (!pathExists(hooksDir) || !fs.statSync(hooksDir).isDirectory()) {
+        return false;
+    }
+    return fs.readdirSync(hooksDir).some((name) => name.endsWith(".py"));
+}
+function listInstalledHookDirs(appHome) {
+    const resolved = resolvePath(appHome);
+    const roots = doctorRoots(resolved);
+    const candidates = [
+        path.join(resolved, "hooks"),
+        path.join(roots.managedAppRoot, "hooks"),
+        path.join(roots.activeBundleRoot, "hooks"),
+    ];
+    const seen = new Set();
+    const out = [];
+    for (const hooksDir of candidates) {
+        const normalized = path.resolve(hooksDir);
+        if (seen.has(normalized) || !hooksDirHasPythonFiles(hooksDir)) {
+            continue;
+        }
+        seen.add(normalized);
+        out.push(hooksDir);
+    }
+    return out;
+}
+export function installedBundleUsesV2PythonHooks(appHome) {
+    return listInstalledHookDirs(appHome).length > 0;
+}
+export function textReferencesV2InstalledHooks(text) {
+    return V2_HOOK_INVOCATION_PATTERNS.some((pattern) => pattern.test(text));
+}
+function shouldScanInstalledHookFile(name) {
+    return (name.endsWith(".json") ||
+        name.endsWith(".toml") ||
+        name.endsWith(".js") ||
+        name.endsWith(".md") ||
+        name.endsWith(".yaml") ||
+        name.endsWith(".yml"));
+}
+/** Scan installed hook manifests for shipped v2 hook command invocations. */
+export function scanInstalledBundleForV2HookInvocations(appHome) {
+    const resolved = resolvePath(appHome);
+    const hits = [];
+    for (const hooksDir of listInstalledHookDirs(resolved)) {
+        const walk = (current) => {
+            for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+                const full = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full);
+                    continue;
+                }
+                if (!shouldScanInstalledHookFile(entry.name)) {
+                    continue;
+                }
+                const rel = path.relative(resolved, full);
+                const text = fs.readFileSync(full, "utf8");
+                if (textReferencesV2InstalledHooks(text)) {
+                    hits.push(rel);
+                }
+            }
+        };
+        walk(hooksDir);
+    }
+    return hits;
+}
+export function detectStaleInstalledHooksSurface(appHome) {
+    return (installedBundleUsesV2PythonHooks(appHome) ||
+        scanInstalledBundleForV2HookInvocations(appHome).length > 0);
+}
+export function planInstalledHooksRetirementItems(ctx) {
+    const appHome = resolvePath(ctx.appHome);
+    const roots = doctorRoots(appHome);
+    if (!hasBundleRootEvidence(roots.activeBundleRoot)) {
+        return [{
+                status: "noop",
+                action: RETIRE_INSTALLED_HOOKS_ACTION,
+                runtime: "installed-app",
+                source: appHome,
+                message: "installed hooks preserved because managed bundle ownership is unproven",
+            }];
+    }
+    const hookDirs = listInstalledHookDirs(appHome);
+    const stale = hookDirs.length > 0 || scanInstalledBundleForV2HookInvocations(appHome).length > 0;
+    if (!stale) {
+        return [
+            {
+                status: "noop",
+                action: RETIRE_INSTALLED_HOOKS_ACTION,
+                runtime: "installed-app",
+                source: appHome,
+                message: "installed app home has no v2 Python hooks surface",
+            },
+        ];
+    }
+    const items = [];
+    for (const hooksDir of hookDirs) {
+        for (const name of fs.readdirSync(hooksDir).filter((entry) => V2_INSTALLED_HOOK_FILES.has(entry))) {
+            const source = path.join(hooksDir, name);
+            const item = {
+                status: "pending",
+                action: RETIRE_INSTALLED_HOOKS_ACTION,
+                runtime: "installed-app",
+                source,
+                target: appHome,
+                message: `will retire marker-owned v2 installed hook ${path.relative(appHome, source)}`,
+                removedPreview: [path.relative(appHome, source)],
+            };
+            const evidenceError = bindMigrationResource(item, "source", source, [appHome], "file");
+            if (evidenceError) {
+                item.status = "blocked";
+                item.message = `installed hook preserved: ${evidenceError}; review the unsafe path manually`;
+            }
+            items.push(item);
+        }
+    }
+    return items;
+}
+export function applyInstalledHooksRetirementItems(items, ctx) {
+    const pending = items.filter((item) => item.action === RETIRE_INSTALLED_HOOKS_ACTION && item.status === "pending");
+    if (pending.length === 0) {
+        return;
+    }
+    try {
+        for (const item of pending)
+            verifyBoundMigrationResource(item, "source");
+        for (const item of pending) {
+            removeBoundMigrationResource(item, "source");
+            item.status = "applied";
+            item.message = `retired v2 installed hook ${path.relative(resolvePath(ctx.appHome), item.source)}`;
+        }
+    }
+    catch (exc) {
+        for (const item of pending) {
+            item.status = "blocked";
+            item.message = `installed hook preserved: ${exc.message}; rerun migration and review it manually`;
+        }
+    }
+}
+export function installedHookPathsAfterMigration(appHome) {
+    const resolved = resolvePath(appHome);
+    const out = [];
+    const walk = (current) => {
+        if (!pathExists(current)) {
+            return;
+        }
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            if (SKIP_HOOK_SCAN_PARTS.has(entry.name)) {
+                continue;
+            }
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "hooks") {
+                    for (const hookEntry of fs.readdirSync(full)) {
+                        if (hookEntry.endsWith(".py")) {
+                            out.push(path.relative(resolved, path.join(full, hookEntry)));
+                        }
+                    }
+                }
+                walk(full);
+            }
+        }
+    };
+    walk(resolved);
+    return out;
+}
+export function installedBundleHasV2HookInvocationText(appHome) {
+    return scanInstalledBundleForV2HookInvocations(appHome).length > 0;
+}
+export function isV2HookScript(filePath) {
+    return isFile(filePath) && filePath.endsWith(".py") && filePath.includes(`${path.sep}hooks${path.sep}`);
+}

package/dist/upgrade/legacyAgentCleanup.js

@@ -0,0 +1,282 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { isFile, pathExists, resolvePath } from "../core/paths.js";
+import { opencodeConfigDir } from "../setup/opencode.js";
+import { bindMigrationResource, removeBoundMigrationResource } from "./migrationPublication.js";
+export const REMOVE_LEGACY_AGENT_ACTION = "remove-legacy-agent";
+/** Literal marker v2 wrote into managed per-capability agent files. */
+const MANAGED_AGENT_MARKER = "<!-- agentera: managed -->";
+/** Closed set of v2 Swedish-verb agent files left orphaned after v3 single-agent copy (#20). */
+export const V2_SWEDISH_VERB_AGENT_FILES = [
+    "dokumentera.md",
+    "hej.md",
+    "inspektera.md",
+    "inspirera.md",
+    "optimera.md",
+    "orkestrera.md",
+    "planera.md",
+    "profilera.md",
+    "realisera.md",
+    "resonera.md",
+    "visionera.md",
+    "visualisera.md",
+];
+const V2_SWEDISH_VERB_AGENT_SET = new Set(V2_SWEDISH_VERB_AGENT_FILES);
+export function isV2SwedishVerbAgentFile(name) {
+    return V2_SWEDISH_VERB_AGENT_SET.has(name);
+}
+/**
+ * Closed set of v2 English-named per-capability agent files replaced by the
+ * single v3 `agentera.md` primary agent. These shipped under `.cursor/agents`
+ * and `.opencode/agents` and must be removed when the managed marker is present.
+ */
+export const V2_ENGLISH_CAPABILITY_AGENT_FILES = [
+    "audit.md",
+    "build.md",
+    "design.md",
+    "discuss.md",
+    "document.md",
+    "optimize.md",
+    "orchestrate.md",
+    "plan.md",
+    "profile.md",
+    "research.md",
+    "status.md",
+    "vision.md",
+];
+const V2_ENGLISH_CAPABILITY_AGENT_SET = new Set(V2_ENGLISH_CAPABILITY_AGENT_FILES);
+export function isV2EnglishCapabilityAgentFile(name) {
+    return V2_ENGLISH_CAPABILITY_AGENT_SET.has(name);
+}
+function regularFileIdentity(filePath) {
+    try {
+        const stat = fs.lstatSync(filePath);
+        return stat.isFile() ? `${stat.dev}:${stat.ino}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+function managedAgentOwnership(filePath) {
+    const identity = regularFileIdentity(filePath);
+    if (!identity)
+        return null;
+    let body;
+    try {
+        body = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (!body.includes(MANAGED_AGENT_MARKER))
+        return null;
+    return {
+        kind: "managed-marker-file",
+        identity,
+        fingerprint: `sha256:${createHash("sha256").update(body).digest("hex")}`,
+    };
+}
+function planAgentFiles(ctx, names, description) {
+    const items = [];
+    for (const { runtime, agentsDir } of legacyAgentScanTargets(ctx)) {
+        let directory;
+        try {
+            directory = fs.lstatSync(agentsDir);
+        }
+        catch {
+            continue;
+        }
+        if (!directory.isDirectory()) {
+            items.push({
+                status: "blocked",
+                action: REMOVE_LEGACY_AGENT_ACTION,
+                runtime,
+                source: agentsDir,
+                message: `preserved ${agentsDir}: the legacy agents path is not a real directory; replace the unsafe path or review it manually`,
+            });
+            continue;
+        }
+        for (const name of names) {
+            const source = path.join(agentsDir, name);
+            let candidate;
+            try {
+                candidate = fs.lstatSync(source);
+            }
+            catch {
+                continue;
+            }
+            if (!candidate.isFile()) {
+                items.push({
+                    status: "blocked",
+                    action: REMOVE_LEGACY_AGENT_ACTION,
+                    runtime,
+                    source,
+                    message: `preserved ${source}: only a marker-owned regular file is eligible; review the unsafe resource manually`,
+                });
+                continue;
+            }
+            const ownership = managedAgentOwnership(source);
+            const item = {
+                status: ownership ? "pending" : "blocked",
+                action: REMOVE_LEGACY_AGENT_ACTION,
+                runtime,
+                source,
+                ...(ownership ? { ownership } : {}),
+                message: ownership
+                    ? `will remove marker-owned v2 ${description} ${name}`
+                    : `preserved ${source}: the legacy filename does not prove Agentera ownership; confirm ownership and remove it manually if appropriate`,
+            };
+            if (ownership) {
+                const evidenceError = bindMigrationResource(item, "source", source, [agentsDir], "file");
+                if (evidenceError) {
+                    item.status = "blocked";
+                    item.message = `preserved ${source}: ${evidenceError}; review the unsafe path manually`;
+                }
+            }
+            items.push(item);
+        }
+    }
+    return items;
+}
+export function legacyAgentScanTargets(ctx) {
+    const project = resolvePath(ctx.project);
+    const home = resolvePath(ctx.home);
+    const appHome = resolvePath(ctx.appHome);
+    const env = ctx.env ?? { HOME: home };
+    const targets = [];
+    const seen = new Set();
+    const push = (runtime, agentsDir) => {
+        const normalized = path.resolve(agentsDir);
+        if (seen.has(normalized)) {
+            return;
+        }
+        seen.add(normalized);
+        targets.push({ runtime, agentsDir: normalized });
+    };
+    push("cursor", path.join(project, ".cursor", "agents"));
+    push("cursor", path.join(home, ".cursor", "agents"));
+    if (appHome !== project && appHome !== home) {
+        push("cursor", path.join(appHome, ".cursor", "agents"));
+    }
+    push("opencode", path.join(opencodeConfigDir(home, env), "agents"));
+    return targets;
+}
+export function scanLegacySwedishVerbAgentPaths(agentsDir) {
+    if (!pathExists(agentsDir) || !fs.statSync(agentsDir).isDirectory()) {
+        return [];
+    }
+    const hits = [];
+    for (const name of fs.readdirSync(agentsDir)) {
+        if (!isV2SwedishVerbAgentFile(name)) {
+            continue;
+        }
+        const filePath = path.join(agentsDir, name);
+        if (isFile(filePath)) {
+            hits.push(filePath);
+        }
+    }
+    return hits.sort();
+}
+/**
+ * Scan an agents directory for v2 English-named per-capability agents that v3
+ * superseded with the single `agentera.md` primary agent. Only files carrying
+ * the managed marker are returned, so user-owned agents without the marker are
+ * preserved.
+ */
+export function scanLegacyCapabilityAgentPaths(agentsDir) {
+    if (!pathExists(agentsDir) || !fs.statSync(agentsDir).isDirectory()) {
+        return [];
+    }
+    const hits = [];
+    for (const name of fs.readdirSync(agentsDir)) {
+        if (!isV2EnglishCapabilityAgentFile(name)) {
+            continue;
+        }
+        const filePath = path.join(agentsDir, name);
+        if (!isFile(filePath)) {
+            continue;
+        }
+        const body = fs.readFileSync(filePath, "utf8");
+        if (body.includes(MANAGED_AGENT_MARKER)) {
+            hits.push(filePath);
+        }
+    }
+    return hits.sort();
+}
+/** Scan a tree for reintroduced Swedish-verb agents (v1LegacyCruft-style guard). */
+export function scanLegacySwedishVerbAgentViolations(root) {
+    const resolved = resolvePath(root);
+    const violations = [];
+    const agentDirs = [
+        path.join(resolved, ".cursor", "agents"),
+        path.join(resolved, ".opencode", "agents"),
+    ];
+    for (const agentsDir of agentDirs) {
+        for (const filePath of scanLegacySwedishVerbAgentPaths(agentsDir)) {
+            violations.push(path.relative(resolved, filePath));
+        }
+    }
+    return violations.sort();
+}
+export function planLegacyAgentCleanupItems(ctx) {
+    return planAgentFiles(ctx, V2_SWEDISH_VERB_AGENT_FILES, "Swedish-verb agent");
+}
+export function planLegacyCapabilityAgentCleanupItems(ctx) {
+    return planAgentFiles(ctx, V2_ENGLISH_CAPABILITY_AGENT_FILES, "per-capability agent");
+}
+export function applyLegacyAgentCleanupItems(items, ctx) {
+    const allowed = new Set(legacyAgentScanTargets(ctx).map(({ agentsDir }) => path.resolve(agentsDir)));
+    for (const item of items) {
+        if (item.status !== "pending" || item.action !== REMOVE_LEGACY_AGENT_ACTION || !item.source) {
+            continue;
+        }
+        const basename = path.basename(item.source);
+        try {
+            if (!allowed.has(path.dirname(path.resolve(item.source)))) {
+                item.status = "blocked";
+                item.message = `preserved ${item.source}: path is outside the legacy agent cleanup allowlist; review it manually`;
+                continue;
+            }
+            const ownership = managedAgentOwnership(item.source);
+            if (!ownership) {
+                let absent = false;
+                try {
+                    fs.lstatSync(item.source);
+                }
+                catch (error) {
+                    absent = error.code === "ENOENT";
+                }
+                if (absent) {
+                    item.status = "noop";
+                    item.message = `legacy agent already absent at ${item.source}`;
+                }
+                else {
+                    item.status = "blocked";
+                    item.message = `preserved ${item.source}: managed marker ownership is missing or unsafe; review it manually`;
+                }
+                continue;
+            }
+            if (item.ownership?.kind !== "managed-marker-file"
+                || item.ownership.identity !== ownership.identity
+                || item.ownership.fingerprint !== ownership.fingerprint) {
+                item.status = "blocked";
+                item.message = `preserved ${item.source}: ownership identity or fingerprint changed after preview; rerun migration and review the resource`;
+                continue;
+            }
+            if ((!isV2SwedishVerbAgentFile(basename) && !isV2EnglishCapabilityAgentFile(basename)) ||
+                !regularFileIdentity(item.source)) {
+                item.status = "noop";
+                item.message = `legacy agent already absent at ${item.source}`;
+                continue;
+            }
+            removeBoundMigrationResource(item, "source");
+            item.status = "applied";
+            item.message = `removed orphaned v2 legacy agent ${basename}`;
+        }
+        catch (exc) {
+            item.status = "blocked";
+            item.message = `preserved ${item.source}: ${exc.message}; rerun migration and review it manually`;
+        }
+    }
+}

package/dist/upgrade/lifecycleUpgrade.js

@@ -0,0 +1,113 @@
+import { appendLifecycleOwnershipJournal, lifecycleOwnershipJournalPath, readLifecycleOwnershipJournal, } from "../runtime/lifecycleOwnershipJournal.js";
+import { secureLifecycleRemovalAvailable } from "../runtime/lifecyclePublication.js";
+import { applyNativeResourceCleanup, previewNativeResourceCleanup, } from "../runtime/nativeResourceCleanup.js";
+export const LIFECYCLE_UPGRADE_SCHEMA = "agentera.lifecycleUpgrade.v1";
+function emptySummary() {
+    return {
+        applied: 0,
+        noop: 0,
+        failed: 0,
+        blocked_unowned: 0,
+        skipped_dependency: 0,
+        action_required: 0,
+        pending: 0,
+    };
+}
+function previewSummary(preview) {
+    const summary = emptySummary();
+    for (const operation of preview.plan.operations) {
+        if (operation.action === "noop")
+            summary.noop += 1;
+        else if (operation.action === "blocked_unowned")
+            summary.blocked_unowned += 1;
+        else if (operation.action === "action_required")
+            summary.action_required += 1;
+        else
+            summary.pending += 1;
+    }
+    return summary;
+}
+function resultSummary(result) {
+    return { ...result.summary, pending: 0 };
+}
+function blockedPlan(plan, reason) {
+    return {
+        ...plan,
+        operations: plan.operations.map((operation) => operation.action === "noop"
+            ? operation
+            : { ...operation, action: "action_required", reason }),
+    };
+}
+function journalBlocksMutation(journal) {
+    return !["absent", "clean"].includes(journal.state);
+}
+function journalBlocker(journal) {
+    const diagnostics = journal.diagnostics
+        .map((diagnostic) => diagnostic.replace(/^\d{20}-[0-9a-f-]{36}\.json:\s*/i, ""));
+    return `ownership journal is ${journal.state}: ${diagnostics.join("; ")}`;
+}
+function statusFor(mode, summary, requiredUnmet) {
+    if (summary.failed > 0
+        || summary.blocked_unowned > 0
+        || summary.skipped_dependency > 0
+        || summary.action_required > 0
+        || requiredUnmet.length > 0)
+        return "non_success";
+    if (mode === "preview" && summary.pending > 0)
+        return "pending";
+    if (mode === "apply" && summary.applied > 0)
+        return "success";
+    return "noop";
+}
+/** Preview or apply one explicit ownership-proven native Agentera resource cleanup. */
+export function runLifecycleUpgrade(args, options = {}) {
+    const journal = readLifecycleOwnershipJournal(lifecycleOwnershipJournalPath(args.appHome));
+    let preview = previewNativeResourceCleanup({
+        resourceId: args.resourceCleanup,
+        home: args.home,
+        ledger: journal.ledger,
+    });
+    if (journalBlocksMutation(journal)) {
+        const reason = journalBlocker(journal);
+        preview = {
+            ...preview,
+            ledgerAuthorization: "blocked",
+            ledgerDiagnostics: [...preview.ledgerDiagnostics, reason],
+            plan: blockedPlan(preview.plan, reason),
+        };
+    }
+    let outputJournal = journal;
+    let nativeResourceCleanup = preview;
+    let cleanupSummary = previewSummary(preview);
+    if (args.apply && !journalBlocksMutation(journal)) {
+        nativeResourceCleanup = applyNativeResourceCleanup(preview, {
+            ...options,
+            approved: true,
+            persistLedger(ledger) {
+                appendLifecycleOwnershipJournal(journal.path, ledger);
+            },
+        });
+        cleanupSummary = resultSummary(nativeResourceCleanup);
+        outputJournal = readLifecycleOwnershipJournal(journal.path);
+    }
+    const requiredUnmet = "plan" in nativeResourceCleanup
+        ? nativeResourceCleanup.plan.operations
+            .filter((operation) => operation.required && operation.action !== "noop")
+            .map((operation) => operation.id)
+        : nativeResourceCleanup.requiredUnmet;
+    const mode = args.apply ? "apply" : "preview";
+    return {
+        schemaVersion: LIFECYCLE_UPGRADE_SCHEMA,
+        mode,
+        status: statusFor(mode, cleanupSummary, requiredUnmet),
+        approval: args.apply ? "approved" : "not_requested",
+        platform: {
+            securePublication: secureLifecycleRemovalAvailable(),
+            requirement: "linux_proc_self_fd",
+        },
+        ownershipJournal: outputJournal,
+        nativeResourceCleanup,
+        cleanupSummary,
+        requiredUnmet,
+    };
+}