agentera 3.0.0-dev.16 → 3.0.0-dev.18

package/dist/runtime/lifecycleAdapters.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { buildRuntimeLifecycleState, loadLifecycleAuthority, } from "./lifecycleAuthority.js";
 import { RUNTIME_ADAPTER_CATEGORIES, loadRuntimeLifecycleAdapterContract, } from "./lifecycleAdapterContract.js";
-import { applyLifecycleOperations, createLifecycleOwnershipManifest, emptyLifecycleOwnershipLedger, planLifecycleOperations, } from "./lifecycleOperations.js";
+import { applyLifecycleOperations, createLifecycleOwnershipManifest, emptyLifecycleOwnershipLedger, LIFECYCLE_MANUAL_REVIEW_GUIDANCE, planLifecycleOperations, } from "./lifecycleOperations.js";
 const STATE_PRIORITY = {
     blocked_unowned: 100,
     action_required: 95,
@@ -50,26 +50,41 @@ function expandResource(declaration, values) {
     if (declaration.kind === "directory_files") {
         let entries;
         try {
-            entries = fs.readdirSync(sourcePath)
+            entries = fs
+                .readdirSync(sourcePath)
                 .filter((name) => name.endsWith(declaration.extension))
                 .sort();
         }
         catch (error) {
-            return [{
+            return [
+                {
                     declaration,
                     sourcePath,
                     destinationPath,
                     sourceError: `could not read declared source directory: ${error.message}`,
-                }];
+                },
+            ];
         }
         if (entries.length === 0) {
-            return [{ declaration, sourcePath, destinationPath, sourceError: "declared source directory is empty" }];
+            return [
+                {
+                    declaration,
+                    sourcePath,
+                    destinationPath,
+                    sourceError: "declared source directory is empty",
+                },
+            ];
         }
         return entries.map((name) => {
             const source = path.join(sourcePath, name);
             const destination = path.join(destinationPath, name);
             if (source === destination) {
-                return { declaration, sourcePath: source, destinationPath: destination, alreadyInPlace: true };
+                return {
+                    declaration,
+                    sourcePath: source,
+                    destinationPath: destination,
+                    alreadyInPlace: true,
+                };
             }
             try {
                 return {
@@ -101,9 +116,17 @@ function expandResource(declaration, values) {
     }
     if (declaration.kind === "symlink") {
         if (!fs.existsSync(sourcePath)) {
-            return [{ declaration, sourcePath, destinationPath, sourceError: "declared symlink source is missing" }];
+            return [
+                {
+                    declaration,
+                    sourcePath,
+                    destinationPath,
+                    sourceError: "declared symlink source is missing",
+                },
+            ];
         }
-        return [{
+        return [
+            {
                 declaration,
                 sourcePath,
                 destinationPath,
@@ -115,10 +138,12 @@ function expandResource(declaration, values) {
                     linkTarget: sourcePath,
                     required: declaration.required,
                 },
-            }];
+            },
+        ];
     }
     try {
-        return [{
+        return [
+            {
                 declaration,
                 sourcePath,
                 destinationPath,
@@ -130,26 +155,35 @@ function expandResource(declaration, values) {
                     content: fs.readFileSync(sourcePath),
                     required: declaration.required,
                 },
-            }];
+            },
+        ];
     }
     catch (error) {
-        return [{
+        return [
+            {
                 declaration,
                 sourcePath,
                 destinationPath,
                 sourceError: `could not read declared source: ${error.message}`,
-            }];
+            },
+        ];
     }
 }
 function nearestPlanState(operation) {
     switch (operation.action) {
-        case "noop": return "confirmed";
-        case "create": return "absent";
+        case "noop":
+            return "confirmed";
+        case "create":
+            return "absent";
         case "update":
-        case "finalize_ownership": return "drifted";
-        case "blocked_unowned": return "blocked_unowned";
-        case "action_required": return operation.ownership === "unowned" ? "blocked_unowned" : "action_required";
-        case "remove": return "action_required";
+        case "finalize_ownership":
+            return "drifted";
+        case "blocked_unowned":
+            return "blocked_unowned";
+        case "action_required":
+            return operation.ownership === "unowned" ? "blocked_unowned" : "action_required";
+        case "remove":
+            return "action_required";
     }
 }
 function probeSkill(location, canonical, surfaces) {
@@ -157,7 +191,13 @@ function probeSkill(location, canonical, surfaces) {
     try {
         const stat = fs.lstatSync(skillFile);
         if (!stat.isFile()) {
-            return { location, canonical, surfaces, state: "drifted", detail: "SKILL.md is not a regular file" };
+            return {
+                location,
+                canonical,
+                surfaces,
+                state: "drifted",
+                detail: "SKILL.md is not a regular file",
+            };
         }
         const handle = fs.openSync(skillFile, "r");
         try {
@@ -165,9 +205,21 @@ function probeSkill(location, canonical, surfaces) {
             fs.readSync(handle, bytes, 0, bytes.length, 0);
             const text = bytes.toString("utf8");
             if (!/^name:\s*agentera\s*$/m.test(text)) {
-                return { location, canonical, surfaces, state: "drifted", detail: "SKILL.md does not declare name: agentera" };
+                return {
+                    location,
+                    canonical,
+                    surfaces,
+                    state: "drifted",
+                    detail: "SKILL.md does not declare name: agentera",
+                };
             }
-            return { location, canonical, surfaces, state: "confirmed", detail: "Agentera SKILL.md detected" };
+            return {
+                location,
+                canonical,
+                surfaces,
+                state: "confirmed",
+                detail: "Agentera SKILL.md detected",
+            };
         }
         finally {
             fs.closeSync(handle);
@@ -175,7 +227,13 @@ function probeSkill(location, canonical, surfaces) {
     }
     catch (error) {
         if (error.code === "ENOENT") {
-            return { location, canonical, surfaces, state: "absent", detail: "Agentera SKILL.md is absent" };
+            return {
+                location,
+                canonical,
+                surfaces,
+                state: "absent",
+                detail: "Agentera SKILL.md is absent",
+            };
         }
         return {
             location,
@@ -220,8 +278,7 @@ function evidenceState(value, category) {
     return "unknown";
 }
 function resourceReports(expanded, plan, category, surfaceId) {
-    const matching = expanded.filter((resource) => resource.declaration.category === category
-        && (resource.declaration.surfaceId === undefined || resource.declaration.surfaceId === surfaceId));
+    const matching = expanded.filter((resource) => resource.declaration.category === category && (resource.declaration.surfaceId === undefined || resource.declaration.surfaceId === surfaceId));
     const evidence = [];
     const states = [];
     const operations = [];
@@ -248,9 +305,7 @@ function resourceReports(expanded, plan, category, surfaceId) {
             });
             continue;
         }
-        const operation = resource.operation
-            ? plan.operations.find((candidate) => candidate.id === resource.operation?.id)
-            : undefined;
+        const operation = resource.operation ? plan.operations.find((candidate) => candidate.id === resource.operation?.id) : undefined;
         const state = operation ? nearestPlanState(operation) : "unknown";
         states.push(state);
         if (operation)
@@ -269,22 +324,35 @@ function resourceReports(expanded, plan, category, surfaceId) {
         operations,
     };
 }
+function hasObservedAgenteraIntegration(surfaceId, expanded, plan, skills) {
+    const resourceIntegration = expanded.some((resource) => {
+        if (resource.declaration.surfaceId !== surfaceId)
+            return false;
+        if (resource.alreadyInPlace)
+            return true;
+        const operation = resource.operation ? plan.operations.find((candidate) => candidate.id === resource.operation?.id) : undefined;
+        return operation !== undefined && operation.state !== "missing";
+    });
+    const skillIntegration = skills.some((skill) => !skill.canonical && skill.surfaces.includes(surfaceId) && !["absent", "unknown", "not_applicable"].includes(skill.state));
+    return resourceIntegration || skillIntegration;
+}
+function lifecycleSurfaceExpected(surface, hostPresence, expanded, plan, skills) {
+    return surface.presence === "required" || hostPresence === true || hasObservedAgenteraIntegration(surface.id, expanded, plan, skills);
+}
 function actionRequiredSummary(operations) {
     const missingParentOperations = operations.filter((operation) => operation.reason === "allowed root is not an existing safe directory");
     if (missingParentOperations.length === operations.length) {
         const parents = [...new Set(missingParentOperations.map((operation) => path.dirname(operation.destination)))];
         return `Create the destination parent ${parents.join(", ")} as a real, non-symlink directory you control, then rerun preview; Agentera will not create or replace it.`;
     }
-    return `Resolve these lifecycle blockers manually, then rerun preview: ${operations
-        .map((operation) => `${operation.id}: ${operation.reason}`)
-        .join("; ")}.`;
+    return `Resolve these lifecycle blockers manually, then rerun preview: ${operations.map((operation) => `${operation.id}: ${operation.reason}`).join("; ")}.`;
 }
 function remediationFor(state, claim, operations, nativeActions, runtimeId, surfaceId, evidencePath, sourceRoot) {
     const blockedOperations = operations.filter((operation) => operation.action === "blocked_unowned");
     if (blockedOperations.length > 0) {
         return {
             kind: "action_required",
-            summary: "The destination is not ledger-owned; review the collision manually. Agentera will not adopt it by name or equality.",
+            summary: LIFECYCLE_MANUAL_REVIEW_GUIDANCE,
             operationIds: blockedOperations.map((operation) => operation.id),
             nativeActions: [],
         };
@@ -342,13 +410,16 @@ function remediationFor(state, claim, operations, nativeActions, runtimeId, surf
         return { kind: "action_required", summary, operationIds: [], nativeActions: [] };
     }
     if (state === "confirmed" || state === "not_applicable") {
-        return { kind: "none", summary: "No remediation is required.", operationIds: [], nativeActions: [] };
+        return {
+            kind: "none",
+            summary: "No remediation is required.",
+            operationIds: [],
+            nativeActions: [],
+        };
     }
     return {
         kind: "unavailable",
-        summary: claim.capability === "unsupported"
-            ? "The host surface is explicitly unsupported."
-            : "No verified safe remediation is declared for this host surface.",
+        summary: claim.capability === "unsupported" ? "The host surface is explicitly unsupported." : "No verified safe remediation is declared for this host surface.",
         operationIds: [],
         nativeActions: [],
     };
@@ -366,11 +437,8 @@ function assertSurfaceRemediationConsistency(category, state, operations, remedi
         throw new Error(`${category}: action-required operation must produce action_required reporting`);
     }
     if (remediation.kind === "repair") {
-        const repairableIds = new Set(operations
-            .filter((operation) => ["create", "update", "finalize_ownership"].includes(operation.action))
-            .map((operation) => operation.id));
-        if (remediation.operationIds.length === 0
-            || remediation.operationIds.some((operationId) => !repairableIds.has(operationId))) {
+        const repairableIds = new Set(operations.filter((operation) => ["create", "update", "finalize_ownership"].includes(operation.action)).map((operation) => operation.id));
+        if (remediation.operationIds.length === 0 || remediation.operationIds.some((operationId) => !repairableIds.has(operationId))) {
             throw new Error(`${category}: repair remediation must reference only repairable plan operations`);
         }
     }
@@ -385,13 +453,20 @@ function categorySurface(runtimeId, surface, category, claim, expected, context,
             source: claim.evidence,
             required: false,
             diagnosisComplete: true,
-            evidence: [{
+            evidence: [
+                {
                     kind: "host_probe",
                     state: "not_applicable",
                     detail: "conditional host surface is absent",
                     surfaceId: surface.id,
-                }],
-            remediation: { kind: "none", summary: "No remediation is required.", operationIds: [], nativeActions: [] },
+                },
+            ],
+            remediation: {
+                kind: "none",
+                summary: "No remediation is required.",
+                operationIds: [],
+                nativeActions: [],
+            },
         };
     }
     let state;
@@ -408,9 +483,7 @@ function categorySurface(runtimeId, surface, category, claim, expected, context,
         evidence = relevant.map((skill) => ({
             kind: "filesystem",
             state: skill.state,
-            detail: skill.canonical
-                ? `${skill.detail}; canonical shared location`
-                : `${skill.detail}; additional discovery location can shadow or collide with canonical Agentera`,
+            detail: skill.canonical ? `${skill.detail}; canonical shared location` : `${skill.detail}; additional discovery location can shadow or collide with canonical Agentera`,
             path: skill.location,
             surfaceId: surface.id,
         }));
@@ -420,9 +493,7 @@ function categorySurface(runtimeId, surface, category, claim, expected, context,
         state = aggregateState([state, resources.state]);
     }
     else if (claim.capability === "repairable" || claim.evidence.startsWith("managed_resource:")) {
-        const resourceCategory = claim.evidence.startsWith("managed_resource:")
-            ? expanded.find((resource) => resource.declaration.id === claim.evidence.slice("managed_resource:".length))?.declaration.category ?? category
-            : category;
+        const resourceCategory = claim.evidence.startsWith("managed_resource:") ? (expanded.find((resource) => resource.declaration.id === claim.evidence.slice("managed_resource:".length))?.declaration.category ?? category) : category;
         const resources = resourceReports(expanded, plan, resourceCategory, surface.id);
         state = resources.state;
         evidence = resources.evidence;
@@ -454,49 +525,59 @@ function categorySurface(runtimeId, surface, category, claim, expected, context,
         catch (error) {
             state = error.code === "ENOENT" ? "absent" : "unknown";
         }
-        evidence = [{ kind: "filesystem", state, detail: claim.evidence, path: evidencePath, surfaceId: surface.id }];
+        evidence = [
+            {
+                kind: "filesystem",
+                state,
+                detail: claim.evidence,
+                path: evidencePath,
+                surfaceId: surface.id,
+            },
+        ];
     }
     else if (claim.evidence.startsWith("env:")) {
         const key = claim.evidence.slice("env:".length);
         const value = (context.env ?? process.env)[key];
         state = value ? "confirmed" : "absent";
-        evidence = [{
+        evidence = [
+            {
                 kind: "environment",
                 state,
                 detail: value ? `${key} is present` : `${key} is absent`,
                 surfaceId: surface.id,
-            }];
+            },
+        ];
     }
     else if (claim.evidence === "canonical_skill") {
         const canonical = skills.find((skill) => skill.canonical && skill.surfaces.includes(surface.id));
         state = canonical?.state ?? "unknown";
-        evidence = [{
+        evidence = [
+            {
                 kind: "filesystem",
                 state,
                 detail: canonical?.detail ?? "canonical skill was not diagnosed",
                 path: canonical?.location,
                 surfaceId: surface.id,
-            }];
+            },
+        ];
         const resources = resourceReports(expanded, plan, "skills", surface.id);
         operations = resources.operations;
         evidence.push(...resources.evidence);
         state = aggregateState([state, resources.state]);
     }
     else {
-        const override = context.categoryEvidence?.[category]?.[surface.id]
-            ?? (category === "trust" ? context.surfaceEvidence?.[surface.id]?.trusted : undefined)
-            ?? (category === "enablement" ? context.surfaceEvidence?.[surface.id]?.enabled : undefined);
+        const override = context.categoryEvidence?.[category]?.[surface.id] ?? (category === "trust" ? context.surfaceEvidence?.[surface.id]?.trusted : undefined) ?? (category === "enablement" ? context.surfaceEvidence?.[surface.id]?.enabled : undefined);
         state = evidenceState(override ?? "unknown", category);
-        evidence = [{
+        evidence = [
+            {
                 kind: "contract",
                 state,
                 detail: override === undefined ? `${claim.evidence}; no verified host observation was supplied` : claim.evidence,
                 surfaceId: surface.id,
-            }];
+            },
+        ];
     }
-    const diagnosisComplete = claim.required
-        ? state !== "unknown" && claim.capability !== "unverified"
-        : true;
+    const diagnosisComplete = claim.required ? state !== "unknown" && claim.capability !== "unverified" : true;
     const remediation = remediationFor(state, claim, operations, nativeActions, runtimeId, surface.id, evidencePath, context.sourceRoot);
     assertSurfaceRemediationConsistency(category, state, operations, remediation);
     return {
@@ -517,7 +598,7 @@ function canonicalDetection(skills) {
         return "unknown";
     return canonical.state === "confirmed" ? true : false;
 }
-function lifecycleObservation(runtimeId, surfaces, hostPresence, categories, canonicalSkillDetected, diagnosisComplete, context) {
+function lifecycleObservation(runtimeId, surfaces, hostPresence, expectedSurfaces, categories, canonicalSkillDetected, diagnosisComplete, context) {
     return {
         runtimeId,
         canonicalSkillDetected,
@@ -525,11 +606,9 @@ function lifecycleObservation(runtimeId, surfaces, hostPresence, categories, can
         unmetMandatoryFields: [],
         surfaces: surfaces.map((surface) => {
             const host = hostPresence[surface.id] ?? "unknown";
-            const expected = surface.presence === "required" || host === true;
+            const expected = expectedSurfaces[surface.id] === true;
             const skill = categories.skills.surfaces.find((item) => item.surfaceId === surface.id);
-            const trust = context.categoryEvidence?.trust?.[surface.id]
-                ?? context.surfaceEvidence?.[surface.id]?.trusted
-                ?? "unknown";
+            const trust = context.categoryEvidence?.trust?.[surface.id] ?? context.surfaceEvidence?.[surface.id]?.trusted ?? "unknown";
             let enabled;
             if (!expected)
                 enabled = "not_applicable";
@@ -544,6 +623,7 @@ function lifecycleObservation(runtimeId, surfaces, hostPresence, categories, can
                 enabled = "unknown";
             return {
                 id: surface.id,
+                applicability: surface.presence === "required" ? "required" : expected ? "conditional" : "not_applicable",
                 evidence: {
                     host_present: host,
                     installed: !expected ? "not_applicable" : canonicalSkillDetected,
@@ -581,11 +661,10 @@ export class RuntimeLifecycleAdapter {
                 throw new Error(`${this.runtimeId}: missing declared resource ${id}`);
             return declaration;
         });
-        const expanded = declarations.flatMap((declaration) => expandResource(declaration, values))
+        const expanded = declarations
+            .flatMap((declaration) => expandResource(declaration, values))
             .map((resource) => {
-            if (resource.declaration.id !== "canonical_skill"
-                || resource.operation?.kind !== "symlink"
-                || !context.canonicalSkillTarget)
+            if (resource.declaration.id !== "canonical_skill" || resource.operation?.kind !== "symlink" || !context.canonicalSkillTarget)
                 return resource;
             const target = path.resolve(context.canonicalSkillTarget);
             return {
@@ -594,12 +673,8 @@ export class RuntimeLifecycleAdapter {
                 operation: { ...resource.operation, linkTarget: target },
             };
         });
-        const operations = expanded.flatMap((resource) => resource.operation ? [resource.operation] : []);
-        const allowedRoots = [...new Set([
-                path.resolve(context.sourceRoot),
-                ...(context.canonicalSkillTarget ? [path.resolve(context.canonicalSkillTarget, "..")] : []),
-                ...expanded.map((resource) => path.dirname(resource.destinationPath)),
-            ])];
+        const operations = expanded.flatMap((resource) => (resource.operation ? [resource.operation] : []));
+        const allowedRoots = [...new Set([path.resolve(context.sourceRoot), ...(context.canonicalSkillTarget ? [path.resolve(context.canonicalSkillTarget, "..")] : []), ...expanded.map((resource) => path.dirname(resource.destinationPath))])];
         const repairPlan = planLifecycleOperations({
             allowedRoots,
             operations,
@@ -609,17 +684,14 @@ export class RuntimeLifecycleAdapter {
         const skills = this.runtime.skillLocations.map((location) => probeSkill(expandTemplate(location.path, values), location.canonical, location.surfaces));
         const hostPresence = {};
         for (const surface of this.runtimeAuthority.surfaces) {
-            hostPresence[surface.id] = context.surfaceEvidence?.[surface.id]?.host_present
-                ?? probeBinary(this.runtime.binaries[surface.id], env);
+            hostPresence[surface.id] = context.surfaceEvidence?.[surface.id]?.host_present ?? probeBinary(this.runtime.binaries[surface.id], env);
         }
+        const expectedSurfaces = Object.fromEntries(this.runtimeAuthority.surfaces.map((surface) => [surface.id, lifecycleSurfaceExpected(surface, hostPresence[surface.id], expanded, repairPlan, skills)]));
         const categories = {};
         for (const category of RUNTIME_ADAPTER_CATEGORIES) {
             const surfaceReports = this.runtimeAuthority.surfaces.map((surface) => {
-                const host = hostPresence[surface.id];
-                const expected = surface.presence === "required" || host === true;
-                return categorySurface(this.runtimeId, surface, category, this.runtime.categories[category][surface.id], expected, context, values, expanded, repairPlan, skills, category === "native_actions"
-                    ? this.runtime.nativeActions.filter((action) => action.surfaceId === surface.id)
-                    : []);
+                const expected = expectedSurfaces[surface.id] === true;
+                return categorySurface(this.runtimeId, surface, category, this.runtime.categories[category][surface.id], expected, context, values, expanded, repairPlan, skills, category === "native_actions" ? this.runtime.nativeActions.filter((action) => action.surfaceId === surface.id) : []);
             });
             categories[category] = {
                 category,
@@ -631,12 +703,9 @@ export class RuntimeLifecycleAdapter {
         }
         const detected = canonicalDetection(skills);
         const requiredSkillReports = categories.skills.surfaces.filter((surface) => surface.required);
-        const diagnosisComplete = detected !== "unknown"
-            && requiredSkillReports.length > 0
-            && requiredSkillReports.every((surface) => surface.diagnosisComplete);
-        const observation = lifecycleObservation(this.runtimeId, this.runtimeAuthority.surfaces, hostPresence, categories, detected, diagnosisComplete, context);
-        const authoritativeState = buildRuntimeLifecycleState(this.authority, [observation])
-            .runtimes.find((runtime) => runtime.runtimeId === this.runtimeId);
+        const diagnosisComplete = detected !== "unknown" && requiredSkillReports.length > 0 && requiredSkillReports.every((surface) => surface.diagnosisComplete);
+        const observation = lifecycleObservation(this.runtimeId, this.runtimeAuthority.surfaces, hostPresence, expectedSurfaces, categories, detected, diagnosisComplete, context);
+        const authoritativeState = buildRuntimeLifecycleState(this.authority, [observation]).runtimes.find((runtime) => runtime.runtimeId === this.runtimeId);
         if (!authoritativeState)
             throw new Error(`${this.runtimeId}: lifecycle authority state is missing`);
         const supportFloor = {
@@ -645,12 +714,7 @@ export class RuntimeLifecycleAdapter {
         };
         const expectedCategorySurfaces = RUNTIME_ADAPTER_CATEGORIES.flatMap((category) => categories[category].surfaces.filter((surface) => surface.expected));
         const degraded = expectedCategorySurfaces.some((surface) => !["confirmed", "not_applicable"].includes(surface.state));
-        const caveats = [
-            ...this.contract.caveats,
-            ...expanded
-                .filter((resource) => resource.sourceError)
-                .map((resource) => `${resource.declaration.id}: ${resource.sourceError}`),
-        ];
+        const caveats = [...this.contract.caveats, ...expanded.filter((resource) => resource.sourceError).map((resource) => `${resource.declaration.id}: ${resource.sourceError}`)];
         return {
             schemaVersion: "agentera.runtimeAdapterReport.v1",
             runtimeId: this.runtimeId,
@@ -686,12 +750,7 @@ export class CopilotLifecycleAdapter extends RuntimeLifecycleAdapter {
     }
 }
 export function runtimeLifecycleAdapters(contract = loadRuntimeLifecycleAdapterContract(), authority = loadLifecycleAuthority()) {
-    return [
-        new OpenCodeLifecycleAdapter(contract, authority),
-        new CodexLifecycleAdapter(contract, authority),
-        new CursorLifecycleAdapter(contract, authority),
-        new CopilotLifecycleAdapter(contract, authority),
-    ];
+    return [new OpenCodeLifecycleAdapter(contract, authority), new CodexLifecycleAdapter(contract, authority), new CursorLifecycleAdapter(contract, authority), new CopilotLifecycleAdapter(contract, authority)];
 }
 export function inspectRuntimeLifecycleAdapters(context, contract = loadRuntimeLifecycleAdapterContract(), authority = loadLifecycleAuthority()) {
     const reports = runtimeLifecycleAdapters(contract, authority).map((adapter) => adapter.inspect(context));